Telephony Providers - Burki Voice AI Docs

Burki Voice AI supports Twilio, Telnyx, and BYO (Bring Your Own) SIP Trunk as telephony providers. You can use different providers for different assistants, enabling cost optimization and redundancy.

Provider Comparison

🏢 Twilio

Traditional Leader

Mature, feature-rich platform
Global presence and reliability
Extensive documentation and community
Higher pricing on calls
Media Streams for real-time audio
SMS/MMS messaging support

⚡ Telnyx

Modern Alternative

Competitive pricing (often 50%+ savings)
Call Control API for advanced features
Developer-friendly modern APIs
SMS/MMS messaging support
Global carrier-grade network
WebRTC and SIP support

🔧 BYO SIP Trunk

Maximum Flexibility

Use any SIP provider (Zadarma, VoIP.ms, etc.)
Potentially lowest costs
Full control over infrastructure
Supports SIP REFER for call transfers
Voice calls only (no SMS typically)
Requires SIP provider configuration

Provider Selection Logic

The system automatically determines which provider to use based on this priority:

Assistant-Level Credentials

Check if the assistant has telnyx_config or twilio_config configuredPriority: Telnyx > Twilio if both are present

Organization-Level Credentials

Fallback to organization-level telephony credentialsPriority: Telnyx > Twilio if both are present

Environment Variables

Use system-wide environment variables as last resortPriority: Telnyx > Twilio if both are present

Twilio Setup

Twilio Configuration

1. Account Setup

Sign up at Twilio Console
Purchase a phone number
Enable Media Streams on your account

2. Webhook Configuration

Set your Twilio webhook URL to:

https://yourdomain.com/twiml

3. Credentials

Environment Variables (Global):

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token

Per-Assistant (API):

{
  "twilio_config": {
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token"
  }
}

4. Features

✅ Inbound/Outbound calls
✅ Call recording
✅ Call transfer
✅ Real-time audio streaming
✅ SMS capabilities
✅ Global phone numbers

Telnyx Setup

Telnyx Configuration

1. Account Setup

Sign up at Telnyx Portal
Purchase a phone number
Create a Call Control Application

2. Call Control Application

Go to Call Control > Applications
Create a new application
Set webhook URL to:
```
https://yourdomain.com/telnyx-webhook
```
Enable Answering Machine Detection (optional)
Save and note the Connection ID

3. Credentials

Environment Variables (Global):

TELNYX_API_KEY=KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELNYX_CONNECTION_ID=1234567890

Per-Assistant (API):

{
  "telnyx_config": {
    "api_key": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "connection_id": "1234567890"
  }
}

4. Features

✅ Inbound/Outbound calls
✅ Call recording
✅ Call transfer
✅ WebRTC support
✅ SMS capabilities
✅ Competitive pricing
⚠️ WebSocket audio streaming (planned)

BYO SIP Trunk Setup

BYO SIP Trunk Configuration

1. Overview

Bring Your Own (BYO) SIP Trunk allows you to integrate any SIP-based telephony provider with Burki Voice AI. This is ideal for:

Cost optimization with existing SIP provider relationships
Regional/specialized SIP providers (Zadarma, VoIP.ms, etc.)
Full control over telephony infrastructure
Integration with on-premise PBX systems

2. Prerequisites

Before setting up BYO SIP trunk:

Purchase phone numbers from your SIP provider
Obtain SIP gateway address (e.g., sip.zadarma.com, sip.voip.ms)
Get SIP authentication credentials (username/password) or configure IP authentication
Configure your provider to forward calls to Burki

3. Network Requirements

Ensure your SIP provider allows traffic to/from these IPs:

44.229.228.186/32
44.238.177.138/32

IP-based authentication can cause routing issues on shared infrastructure. Use credential-based authentication when possible.

4. Organization-Level Configuration

Environment Variables (Global):

SIP_GATEWAY=sip.zadarma.com
SIP_USERNAME=15551234567
SIP_PASSWORD=your_sip_password

API Configuration:

curl -X PUT "https://yourdomain.com/api/v1/organizations/{org_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sip_gateway": "sip.zadarma.com",
    "sip_username": "15551234567",
    "sip_password": "your_sip_password",
    "sip_trunk_config": {
      "sip_domain": "zadarma.com",
      "inbound_enabled": true,
      "outbound_leading_plus_enabled": true,
      "auth_plan": {
        "type": "credentials",
        "username": "15551234567",
        "password": "your_sip_password"
      }
    }
  }'

5. Register Phone Numbers

curl -X POST "https://yourdomain.com/api/v1/phone-numbers/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "provider": "byo-sip-trunk",
    "friendly_name": "My SIP Number",
    "assistant_id": 123
  }'

6. Configure Provider Webhooks

Configure your SIP provider to forward inbound calls to:

https://yourdomain.com/sip-webhook

For specific SIP URI format (varies by provider):

sip:{phone_number}@{your-burki-domain}.com

7. Outbound Calls

Initiate outbound calls through your SIP trunk:

curl -X POST "https://yourdomain.com/api/v1/calls/initiate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone_number": "+15557654321",
    "from_phone_number": "+15551234567",
    "assistant_id": 123
  }'

8. Call Transfers (SIP REFER)

For call transfers, configure the transfer tool with SIP URI format:

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "sip",
      "sipUri": "sip:+15557654321@sip.zadarma.com"
    }
  ]
}

Some providers require E.164 formatting with the + prefix: sip:+15557654321@sip.provider.com

9. Provider-Specific Examples

Zadarma
VoIP.ms
Generic SIP

{
  "sip_gateway": "sip.zadarma.com",
  "sip_username": "YOUR_SIP_NUMBER",
  "sip_password": "YOUR_SIP_PASSWORD",
  "sip_trunk_config": {
    "inbound_enabled": false,
    "outbound_leading_plus_enabled": true,
    "auth_plan": {
      "type": "credentials"
    }
  }
}

10. Features & Limitations

Supported:

✅ Inbound calls (with provider webhook configuration)
✅ Outbound calls
✅ Call transfers (SIP REFER)
✅ Call recording (application-level)
✅ Credential-based and IP-based authentication

Not Supported:

❌ SMS/MMS (most SIP trunks are voice-only)
❌ Phone number search/purchase via API (use provider portal)
❌ Automatic webhook configuration (manual setup required)

11. Troubleshooting

401 Unauthorized Errors

Verify SIP credentials are correct
Ensure all signaling IP addresses are whitelisted
Check if IP-based auth is properly configured

Calls Not Routing

Confirm webhook URL is accessible from your provider
Check SIP URI format matches provider requirements
Verify phone number is registered in Burki database

Transfer Not Working

Enable SIP REFER on your provider
Verify transfer destination format (some providers require E.164)
Check provider supports blind transfers

Mixed Environment Examples

Use Case 1: Cost Optimization

// High-volume sales assistant - use BYO SIP for lowest costs
{
  "name": "Sales Dialer Bot",
  "phone_numbers": [
    {
      "phone_number": "+15551234567",
      "provider": "byo-sip-trunk"
    }
  ]
}

// Standard support - use Telnyx for good balance
{
  "name": "Support Bot",
  "phone_numbers": [
    {
      "phone_number": "+15559876543",
      "provider": "telnyx"
    }
  ]
}

// Premium support assistant - use Twilio for reliability
{
  "name": "VIP Support Bot", 
  "phone_numbers": [
    {
      "phone_number": "+15555555555",
      "provider": "twilio"
    }
  ]
}

Use Case 2: Geographic Optimization

// US/Canada assistant - use Telnyx for better rates
{
  "name": "North America Bot",
  "telnyx_config": {
    "api_key": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "connection_id": "1234567890"
  }
}

// International assistant - use Twilio for global coverage
{
  "name": "Global Support Bot",
  "twilio_config": {
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 
    "auth_token": "your_twilio_auth_token"
  }
}

Provider Migration

Gradual Migration

You can migrate assistants from one provider to another without downtime:

{
  "name": "Customer Service Bot",
  "twilio_config": {
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token"
  }
}

Bulk Migration

Use the API to migrate multiple assistants:

import requests

# List all assistants
assistants = requests.get("/api/v1/assistants").json()

# Migrate each one
for assistant in assistants:
    requests.put(f"/api/v1/assistants/{assistant['id']}", json={
        "telnyx_config": {
            "api_key": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "connection_id": "1234567890"
        },
        "twilio_config": {
            "account_sid": None,
            "auth_token": None
        }
    })

Troubleshooting

Call Not Connecting

Check:

Webhook URLs are correct and accessible
Credentials are valid and have proper permissions
Phone number is assigned to correct assistant
Provider account has sufficient balance

Poor Audio Quality

Twilio: Ensure Media Streams are enabledTelnyx: Check Call Control Application settingsBoth: Verify network connectivity and bandwidth

Provider Detection Issues

Check priority order:

Assistant-level config
Organization-level config
Environment variables

Debug: Check assistant object in API response to see detected provider

Best Practices

Start with one provider and add the second for specific use cases
Test thoroughly when switching providers for existing assistants
Monitor costs and usage patterns to optimize provider selection
Keep credentials secure and rotate them regularly
Use environment variables for global defaults, per-assistant config for exceptions

Getting Started

Core Concepts

AI Providers

Features

Advanced

Help & Resources

​Provider Comparison

🏢 Twilio

⚡ Telnyx

🔧 BYO SIP Trunk

​Provider Selection Logic

​Twilio Setup

​1. Account Setup

​2. Webhook Configuration

​3. Credentials

​4. Features

​Telnyx Setup

​1. Account Setup

​2. Call Control Application

​3. Credentials

​4. Features

​BYO SIP Trunk Setup

​1. Overview

​2. Prerequisites

​3. Network Requirements

​4. Organization-Level Configuration

​5. Register Phone Numbers

​6. Configure Provider Webhooks

​7. Outbound Calls

​8. Call Transfers (SIP REFER)

​9. Provider-Specific Examples

​10. Features & Limitations

​11. Troubleshooting

​Mixed Environment Examples

​Use Case 1: Cost Optimization

​Use Case 2: Geographic Optimization

​Provider Migration

​Gradual Migration

​Bulk Migration

​Troubleshooting

​Best Practices

​What’s Next?

📞 Call Management

🎙️ Audio Configuration

Provider Comparison

Provider Selection Logic

Twilio Setup

1. Account Setup

2. Webhook Configuration

3. Credentials

4. Features

Telnyx Setup

1. Account Setup

2. Call Control Application

3. Credentials

4. Features

BYO SIP Trunk Setup

1. Overview

2. Prerequisites

3. Network Requirements

4. Organization-Level Configuration

5. Register Phone Numbers

6. Configure Provider Webhooks

7. Outbound Calls

8. Call Transfers (SIP REFER)

9. Provider-Specific Examples

10. Features & Limitations

11. Troubleshooting

Mixed Environment Examples

Use Case 1: Cost Optimization

Use Case 2: Geographic Optimization

Provider Migration

Gradual Migration

Bulk Migration

Troubleshooting

Best Practices

What’s Next?