SIP Credentials and Trunk Configuration

Configure SIP credentials to connect your organization to any VoIP provider. Credentials are shared across your organization — create them once, then link phone numbers to use them. What you’ll learn: How to configure SIP credentials, choose transport protocols, set up rate limiting, and troubleshoot connection issues.

SIP credentials overview

SIP credentials store the authentication details for your SIP trunk provider. Create credentials once at the organization level, then link multiple phone numbers to use them.

Create SIP credentials

Dashboard
API

Navigate to Phone Numbers → Credentials tab
Click Add Credentials
Fill in the configuration fields
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.provider.com:5060',
    authUser: 'your-username',
    authPassword: 'your-password',
    domain: 'sip.provider.com',
    transport: 'udp',
    description: 'Production Trunk'
  })
});

const credentials = await response.json();

Configuration fields

Required

Field	Format	Description
`server`	`hostname:port`	SIP server address. Include port if non-standard (default: 5060)

Authentication

Field	Description
`authUser`	Username for SIP authentication (provided by your provider)
`authPassword`	Password for SIP authentication
`domain`	SIP domain/realm for authentication (often same as server hostname)

Transport

Field	Values	Description
`transport`	`udp`, `tcp`, `tls`	Protocol for SIP signaling (default: `udp`)

Rate limiting

Field	Description
`cpsLimit`	Maximum calls per second through this trunk
`cpsKey`	Shared key to combine rate limits across multiple credentials

Transport protocols

Choose the right transport based on your requirements:

Protocol	Port	Encryption	Use when
UDP	5060	No	Standard setup, lowest latency
TCP	5060	No	Behind restrictive firewalls
TLS	5061	Yes	Security/compliance requirements

Example: TLS configuration

{
  server: 'sip.provider.com:5061',
  authUser: 'your-username',
  authPassword: 'your-password',
  transport: 'tls'
}

Rate limiting

Control call pacing to avoid exceeding your provider’s limits.

Single trunk limit

{
  server: 'sip.provider.com',
  authUser: 'trunk-1',
  cpsLimit: 10  // Max 10 calls/second
}

Shared limit across trunks

When you have multiple trunks with a shared rate limit from your provider:

// Trunk 1
{
  server: 'sip.provider.com',
  authUser: 'trunk-1',
  cpsLimit: 20,
  cpsKey: 'provider-shared'  // Share limit with trunk-2
}

// Trunk 2
{
  server: 'sip.provider.com',
  authUser: 'trunk-2',
  cpsLimit: 20,
  cpsKey: 'provider-shared'  // Combined limit: 20 CPS total
}

Provider-managed credentials

When you connect a Twilio provider, SIP credentials are created automatically:

Source: Shows as provider instead of manual
Read-only: Cannot modify provider-managed credentials
Lifecycle: Deleted when the provider is deleted

// Response shows source type
{
  id: 'cred-123',
  source: 'provider',      // Created by Twilio integration
  providerId: 'prov-456',  // Reference to Twilio provider
  server: 'sip.twilio.com'
  // ... other fields
}

Check credential usage

Before modifying or deleting credentials, check which phone numbers and agents depend on them:

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

console.log('Phone numbers using these credentials:');
affected.phoneNumbers.forEach(pn => {
  console.log(`  ${pn.phoneNumber} → Agent: ${pn.linkedAgent?.name || 'none'}`);
});

console.log('Queued calls:', affected.queuedCallsCount);

Delete credentials

Deleting credentials also deletes all associated phone numbers and updates affected agents.

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

if (affected.queuedCallsCount > 0) {
  console.log('Warning: calls in queue will fail');
}

// Delete with force flag if phone numbers exist
await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}?force=true`,
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

Troubleshooting

Authentication failures

Error	Cause	Fix
401 Unauthorized	Wrong username/password	Verify credentials in provider portal
403 Forbidden	IP not whitelisted	Add Dasha IPs to provider allowlist
Domain mismatch	Wrong `domain` value	Check provider’s authentication realm

Connection issues

Error	Cause	Fix
Timeout	Wrong server/port	Verify `server` address and port
Connection refused	Wrong transport	Try `tcp` instead of `udp` (or vice versa)
TLS handshake failed	Certificate issue	Check provider supports TLS; verify port 5061

Rate limiting

Error	Cause	Fix
503 Service Unavailable	Exceeded provider CPS	Set `cpsLimit` below provider’s limit
Calls dropping	Shared limit exceeded	Use `cpsKey` to combine trunk limits

Next steps

Phone Numbers

Add and link phone numbers

Caller ID

Configure display names

Inbound Calls

Handle incoming calls

Outbound Calls

Make outbound calls

Introduction

Create

Test

Deploy

Monitor

Advanced Features

Troubleshooting

SIP credentials overview

Create SIP credentials

Configuration fields

Required

Authentication

Transport

Rate limiting

Transport protocols

Rate limiting

Single trunk limit

Shared limit across trunks

Provider-managed credentials

Check credential usage

Delete credentials

Troubleshooting

Authentication failures

Connection issues

Rate limiting

Next steps

Phone Numbers

Caller ID

Inbound Calls

Outbound Calls

​SIP credentials overview

​Create SIP credentials

​Configuration fields

​Required

​Authentication

​Transport

​Rate limiting

​Transport protocols

​Rate limiting

​Single trunk limit

​Shared limit across trunks

​Provider-managed credentials

​Check credential usage

​Delete credentials

​Troubleshooting

​Authentication failures

​Connection issues

​Rate limiting

​Next steps

Phone Numbers

Caller ID

Inbound Calls

Outbound Calls

SIP credentials overview

Create SIP credentials

Configuration fields

Required

Authentication

Transport

Rate limiting

Transport protocols

Rate limiting

Single trunk limit

Shared limit across trunks

Provider-managed credentials

Check credential usage

Delete credentials

Troubleshooting

Authentication failures

Connection issues

Rate limiting

Next steps