Connect Phone Numbers to Your Agents - Dasha BlackBox Documentation

Connect phone numbers to receive inbound calls and make outbound calls. Use the Twilio integration for automatic setup, or manually configure SIP credentials from any provider. What you’ll learn: How to add phone numbers via Twilio or manual SIP configuration, link numbers to agents, and manage your telephony setup.

Two ways to add phone numbers

Method	Setup time	Best for
Twilio integration	2 minutes	Quick setup, automatic SIP trunk configuration
Manual SIP credentials	5-10 minutes	Any SIP provider (Telnyx, Bandwidth, Vonage, etc.)

Option 1: Twilio integration

Connect your Twilio account and import phone numbers with automatic SIP trunk configuration.

Step 1: Create Twilio provider

Dashboard
API

Navigate to Phone Numbers in the sidebar
Click Add Provider → Twilio
Enter your Twilio Account SID and Auth Token
Click Connect

const response = await fetch('https://blackbox.dasha.ai/api/v1/providers/twilio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Twilio Account',
    accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    authToken: 'your-auth-token'
  })
});

const provider = await response.json();
console.log('Provider created:', provider.id);

This automatically:

Creates a SIP trunk in your Twilio account
Generates SIP credentials for authentication
Stores everything securely in your organization

Step 2: Import phone numbers

Dashboard
API

In your Twilio provider, click Import Numbers
Select the phone numbers you want to use
Click Import Selected

// First, list available numbers
const available = await fetch(
  `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/available-numbers`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log('Available numbers:', available);

// Import selected numbers
const result = await fetch(
  `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/import-numbers`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phoneNumberSids: ['PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']
    })
  }
).then(r => r.json());

console.log(`Imported: ${result.successCount}, Failed: ${result.failedCount}`);

Step 3: Link to agent

See Link phone numbers to agents below.

Option 2: Manual SIP credentials

Configure SIP credentials from any provider (Telnyx, Bandwidth, Vonage, or others).

Step 1: Create SIP credentials

Dashboard
API

Navigate to Phone Numbers → Credentials tab
Click Add Credentials
Enter your SIP provider details:
- Server: SIP server address (e.g., sip.telnyx.com)
- Auth User: Your SIP username
- Password: Your SIP password
- Transport: UDP, TCP, or TLS
Click Save

const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-credentials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server: 'sip.telnyx.com',
    authUser: 'your-username',
    authPassword: 'your-password',
    transport: 'udp',
    description: 'Telnyx Production Trunk'
  })
});

const credentials = await response.json();
console.log('Credentials ID:', credentials.id);

Step 2: Add phone numbers

Dashboard
API

Navigate to Phone Numbers → Numbers tab
Click Add Number
Enter the phone number and select credentials
Enable Registration if your provider requires it
Click Save

const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-phone-numbers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: '+14155551234',
    credentialsId: 'your-credentials-id',
    displayName: 'Support Line',
    registration: true
  })
});

const phoneNumber = await response.json();
console.log('Phone number ID:', phoneNumber.id);

Step 3: Link to agent

See Link phone numbers to agents below.

Link phone numbers to agents

After adding phone numbers, link them to agents for inbound routing or outbound calling.

For inbound calls

Link a phone number to an agent so incoming calls route to that agent:

Dashboard
API

Go to Phone Numbers → Numbers tab
Click on a phone number
Select an agent from the Inbound Agent dropdown
Click Save

await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=inbound`,
  {
    method: 'PUT',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

For outbound calls

Set a phone number as an agent’s outbound caller ID:

Dashboard
API

Go to Agents → Select agent → Edit
In the Outbound Phone Number section, select a number
Click Save Agent

await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=replaceOutbound`,
  {
    method: 'PUT',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

SIP credentials reference

Field	Required	Description
`server`	Yes	SIP server hostname with optional port (e.g., `sip.provider.com:5060`)
`authUser`	No	Authentication username
`authPassword`	No	Authentication password
`domain`	No	SIP domain for authentication realm
`transport`	No	Protocol: `udp` (default), `tcp`, or `tls`
`description`	No	Human-readable label
`cpsLimit`	No	Max calls per second through this trunk
`cpsKey`	No	Shared rate limit key across multiple credentials

Phone number reference

Field	Required	Description
`phoneNumber`	Yes	Phone number (E.164 format recommended)
`credentialsId`	Yes	SIP credentials to use for this number
`displayName`	No	Caller ID display name
`description`	No	Human-readable label
`registration`	No	Enable SIP registration (default: false)

Check what’s using a phone number

Before modifying or deleting, see which agents use a phone number:

const affected = await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/affected-agents`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log('Inbound agent:', affected.inboundAgent);
console.log('Outbound agents:', affected.outboundAgents);

Troubleshooting

Registration failing

Symptom	Fix
Status shows “Not registered”	Check credentials are correct; verify provider requires registration
401 Unauthorized	Verify `authUser` and `authPassword` match provider exactly
Timeout errors	Check `server` address and port; try different `transport`

Inbound calls not connecting

Symptom	Fix
Calls go to voicemail	Verify phone number is linked to an agent
404 Not Found	Check the phone number exists and registration succeeded
Agent doesn’t answer	Verify agent is enabled and has valid configuration

Outbound calls failing

Symptom	Fix
”No outbound config”	Link a phone number to the agent for outbound
Authentication errors	Verify SIP credentials are correct
Invalid caller ID	Ensure phone number is verified with your provider

Next steps

Inbound Calls

Handle incoming calls

Outbound Calls

Make outbound calls via API

Caller ID

Configure display names

SIP Configuration

Advanced SIP settings

Documentation Index

​Two ways to add phone numbers

​Option 1: Twilio integration

​Step 1: Create Twilio provider

​Step 2: Import phone numbers

​Step 3: Link to agent

​Option 2: Manual SIP credentials

​Step 1: Create SIP credentials

​Step 2: Add phone numbers

​Step 3: Link to agent

​Link phone numbers to agents

​For inbound calls

​For outbound calls

​SIP credentials reference

​Phone number reference

​Check what’s using a phone number

​Troubleshooting

​Registration failing

​Inbound calls not connecting

​Outbound calls failing

​Next steps

Inbound Calls

Outbound Calls

Caller ID

SIP Configuration

Two ways to add phone numbers

Option 1: Twilio integration

Step 1: Create Twilio provider

Step 2: Import phone numbers

Step 3: Link to agent

Option 2: Manual SIP credentials

Step 1: Create SIP credentials

Step 2: Add phone numbers

Step 3: Link to agent

Link phone numbers to agents

For inbound calls

For outbound calls

SIP credentials reference

Phone number reference

Check what’s using a phone number

Troubleshooting

Registration failing

Inbound calls not connecting

Outbound calls failing

Next steps