Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blackbox.dasha.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

  1. Navigate to Phone Numbers → Credentials tab
  2. Click Add Credentials
  3. Fill in the configuration fields
  4. Click Save

​
Configuration fields

​
Required

FieldFormatDescription
serverhostname:portSIP server address. Include port if non-standard (default: 5060)

​
Authentication

FieldDescription
authUserUsername for SIP authentication (provided by your provider)
authPasswordPassword for SIP authentication
domainSIP domain/realm for authentication (often same as server hostname)

​
Transport

FieldValuesDescription
transportudp, tcp, tlsProtocol for SIP signaling (default: udp)

​
Rate limiting

FieldDescription
cpsLimitMaximum calls per second through this trunk
cpsKeyShared key to combine rate limits across multiple credentials

​
Transport protocols

Choose the right transport based on your requirements:
ProtocolPortEncryptionUse when
UDP5060NoStandard setup, lowest latency
TCP5060NoBehind restrictive firewalls
TLS5061YesSecurity/compliance requirements
{
  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

ErrorCauseFix
401 UnauthorizedWrong username/passwordVerify credentials in provider portal
403 ForbiddenIP not whitelistedAdd Dasha IPs to provider allowlist
Domain mismatchWrong domain valueCheck provider’s authentication realm

​
Connection issues

ErrorCauseFix
TimeoutWrong server/portVerify server address and port
Connection refusedWrong transportTry tcp instead of udp (or vice versa)
TLS handshake failedCertificate issueCheck provider supports TLS; verify port 5061

​
Rate limiting

ErrorCauseFix
503 Service UnavailableExceeded provider CPSSet cpsLimit below provider’s limit
Calls droppingShared limit exceededUse 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