Skip to main content
PUT
/
api
/
v1
/
sip-phone-numbers
/
{id}
/
agent-link
Link phone number to agent
const options = {method: 'PUT', headers: {Authorization: 'Bearer <token>'}};

fetch('https://blackbox.dasha.ai/api/v1/sip-phone-numbers/{id}/agent-link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "orgId": "<string>",
  "phoneNumber": "<string>",
  "credentialsId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdTime": "2023-11-07T05:31:56Z",
  "lastUpdateTime": "2023-11-07T05:31:56Z",
  "registrationStatus": {
    "state": "Disabled",
    "errorDescription": "<string>",
    "sipResponseMessage": "<string>",
    "lastUpdated": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "description": "<string>",
  "displayName": "<string>",
  "registration": true,
  "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "incomingCallsAgentId": "<string>"
}
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.
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.

​
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)

Path Parameters

​
id
string<uuid>
required

Phone number identifier

Query Parameters

​
agentId
string
required

Agent identifier

​
mode
enum<string>
default:inbound

Link mode: "inbound" for inbound call routing (default), "replaceOutbound" to set as agent's outbound number Specifies the type of agent-phone number link operation.

Available options:
inbound,
replaceOutbound

Response

Phone number linked to agent successfully

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.

​
id
string<uuid>
required

Unique identifier for this phone number configuration. Use this ID when referencing the number in agent configurations or API calls.

​
orgId
string
required

Organization that owns this phone number. Used for access control and resource isolation.

Minimum string length: 1
​
phoneNumber
string
required

Phone number configured for outbound calling or inbound routing.

Minimum string length: 1
​
credentialsId
string<uuid>
required

SIP credentials used by this phone number. References the trunk configuration that handles authentication and routing for calls.

​
createdTime
string<date-time>
required

Timestamp when this phone number configuration was originally created.

​
lastUpdateTime
string<date-time>
required

Timestamp when this phone number configuration was last modified. Updates when settings like DisplayName, Registration, or IncomingCallsAgentId change.

​
registrationStatus
object
required

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.

​
description
string | null

Human-readable description of this phone number. Helps document the number's purpose or usage.

​
displayName
string | null

Display name shown in caller ID when making outbound calls with this number. Helps recipients identify the caller.

​
registration
boolean

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
string<uuid> | null

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.

​
incomingCallsAgentId
string | null

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.