> ## Documentation Index
> Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Link phone number to agent

> Links a SIP phone number to an agent for handling inbound or outbound calls.
If the phone number was previously linked to another agent for inbound, it will
automatically unlink from the previous agent and link to the new one.
For outbound, replaces the agent's current outbound phone number (only one supported).

<Warning>If the phone number is already linked to a different agent for inbound, the previous agent link will be automatically removed and replaced with the new agent link.</Warning>

<Note>When linking a phone number to an agent for inbound, the phone number must be globally unique across the entire system for this operation. If the same phone number is already linked in another organization, the linking operation will fail.</Note>

## Inbound Call Routing (mode=inbound)

When a phone number is linked to an agent for inbound:

* Inbound calls to this number are automatically routed to the agent
* The agent handles the conversation using its configured voice and behavior
* Only one agent can be linked to a phone number at a time for inbound

## Outbound Calling (mode=replaceOutbound)

When a phone number is linked to an agent for outbound:

* The agent can use this phone number as caller ID when making outbound calls
* Replaces any existing outbound phone number for the agent (only one supported)

## Use Cases

* Dedicated customer support lines (mode=inbound)
* Campaign-specific tracking numbers (mode=inbound)
* Outbound calling with specific caller ID (mode=replaceOutbound)


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/sip-phone-numbers/{id}/agent-link
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - ApiKey: []
  - OAuth: []
tags:
  - name: ActivityLogs
  - name: Agents
  - name: AgentTestCases
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: Copilot
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/sip-phone-numbers/{id}/agent-link:
    put:
      tags:
        - SipPhoneNumbers
      summary: Link phone number to agent
      description: >-
        Links a SIP phone number to an agent for handling inbound or outbound
        calls.

        If the phone number was previously linked to another agent for inbound,
        it will

        automatically unlink from the previous agent and link to the new one.

        For outbound, replaces the agent's current outbound phone number (only
        one supported).
      parameters:
        - name: id
          in: path
          description: Phone number identifier
          required: true
          schema:
            type: string
            format: uuid
        - name: agentId
          in: query
          description: Agent identifier
          required: true
          schema:
            type: string
        - name: mode
          in: query
          description: >-
            Link mode: "inbound" for inbound call routing (default),
            "replaceOutbound" to set as agent's outbound number
          schema:
            allOf:
              - $ref: '#/components/schemas/AgentLinkMode'
            description: Specifies the type of agent-phone number link operation.
            default: inbound
      responses:
        '200':
          description: Phone number linked to agent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipPhoneNumberResponseDto'
        '400':
          description: Invalid agent identifier or invalid mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Phone number or agent with specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Linking conflict occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error occurred during linking
components:
  schemas:
    AgentLinkMode:
      enum:
        - inbound
        - replaceOutbound
      type: string
      description: Specifies the type of agent-phone number link operation.
    SipPhoneNumberResponseDto:
      required:
        - createdTime
        - credentialsId
        - id
        - lastUpdateTime
        - orgId
        - phoneNumber
        - registrationStatus
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this phone number configuration. Use this ID
            when referencing the number in agent configurations or API calls.
          format: uuid
        orgId:
          minLength: 1
          type: string
          description: >-
            Organization that owns this phone number. Used for access control
            and resource isolation.
        phoneNumber:
          minLength: 1
          type: string
          description: Phone number configured for outbound calling or inbound routing.
        credentialsId:
          type: string
          description: >-
            SIP credentials used by this phone number. References the trunk
            configuration that handles authentication and routing for calls.
          format: uuid
        description:
          type: string
          description: >-
            Human-readable description of this phone number. Helps document the
            number's purpose or usage.
          nullable: true
        displayName:
          type: string
          description: >-
            Display name shown in caller ID when making outbound calls with this
            number. Helps recipients identify the caller.
          nullable: true
        registration:
          type: boolean
          description: >-
            Whether SIP registration is performed for this phone number. Some
            SIP providers require registration before making calls. Indicates if
            registration is enabled for this configuration.
        providerId:
          type: string
          description: >-
            Reference to the VoIP provider that manages this phone number.
            Present only for provider-imported phone numbers. When present, the
            provider handles phone number lifecycle and trunk configuration.
          format: uuid
          nullable: true
        incomingCallsAgentId:
          type: string
          description: >-
            Agent that handles inbound calls to this phone number. When
            specified, incoming calls automatically route to this agent. When
            not set, inbound calls to this number are not answered.
          nullable: true
        createdTime:
          type: string
          description: >-
            Timestamp when this phone number configuration was originally
            created.
          format: date-time
        lastUpdateTime:
          type: string
          description: >-
            Timestamp when this phone number configuration was last modified.
            Updates when settings like DisplayName, Registration, or
            IncomingCallsAgentId change.
          format: date-time
        registrationStatus:
          allOf:
            - $ref: '#/components/schemas/SIPRegistrationStatusDTO'
          description: >-
            Current SIP registration status for this phone number. Indicates
            whether the number is successfully registered with the SIP provider
            and able to receive inbound calls.
      additionalProperties: false
      description: >-
        SIP phone number configuration including associated credentials, caller
        ID settings, inbound routing, and registration status. Contains all
        information needed to use this number for making and receiving calls.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    SIPRegistrationStatusDTO:
      type: object
      properties:
        state:
          allOf:
            - $ref: '#/components/schemas/RegistartionState'
          description: The current registration state.
        errorDescription:
          type: string
          description: Human-readable error description for failed registrations.
          nullable: true
        sipResponseMessage:
          type: string
          description: Full SIP response message for failed registrations.
          nullable: true
        lastUpdated:
          type: string
          description: When the status was last updated.
          format: date-time
        expiresAt:
          type: string
          description: >-
            When the registration expires. Null for failed or disabled
            registrations.
          format: date-time
          nullable: true
      additionalProperties: false
    RegistartionState:
      enum:
        - Disabled
        - InProgress
        - Succeeded
        - InProgressWithAuth
        - Initialized
        - Unknown
        - Failed
      type: string
      description: Represents the state of a SIP registration.
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authentication (Bearer {key})
      scheme: Bearer
    OAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.dasha.ai/connect/authorize
          scopes:
            platform_api: Platform API

````