Twilio Integration

Twilio is the most widely-used cloud communications platform, offering excellent global coverage and robust APIs.

Why Twilio?

• Global Coverage: 180+ countries
• Reliable Infrastructure: 99.95% uptime SLA
• Excellent Documentation: Best-in-class developer experience
• Native WebSocket: First-class streaming support via Media Streams

Prerequisites

1. Twilio account (sign up at twilio.com)
2. A phone number capable of voice calls
3. Account SID and Auth Token

Configuration

Environment Variables

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

TwiML Configuration

For inbound calls, configure your Twilio phone number's webhook to return TwiML that connects to your WebSocket:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Connect>
        <Stream url="wss://your-domain.com/agent/{agentId}/user/{userId}/">
            <Parameter name="agentId" value="{agentId}"/>
        </Stream>
    </Connect>
</Response>

Call Flows

Inbound Call Flow

1. Caller dials your Twilio number
          ↓
2. Twilio requests TwiML from your webhook
          ↓
3. Your server returns TwiML with <Stream> element
          ↓
4. Twilio connects WebSocket to specified URL
          ↓
5. Bidirectional audio streaming begins
          ↓
6. Voice agent handles conversation

Outbound Call Flow

1. POST /make-call with agent_id, phone_number
          ↓
2. TwilioMakeCall() builds TwiML with WebSocket URL
          ↓
3. POST to Twilio API to initiate call
          ↓
4. Twilio dials recipient
          ↓
5. On answer, Twilio connects to WebSocket
          ↓
6. Voice agent handles conversation

API Reference

Make Outbound Call

POST /make-call
Content-Type: application/json

{
  "agent_id": "123",
  "phone_number": "+1234567890",
  "workspace_id": "ws_456",
  "call_provider": "twilio",
  "variables": {
    "customer_name": "John Doe",
    "order_id": "ORD-12345"
  }
}

Need your workspace ID? See Finding Your Workspace ID.

Response:

{
  "status": "success",
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

WebSocket Message Format

Twilio uses camelCase for message fields:

Connected Message:

{
  "event": "connected",
  "protocol": "Call",
  "version": "1.0.0"
}

Start Message:

{
  "event": "start",
  "sequenceNumber": "1",
  "start": {
    "streamSid": "MZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "callSid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "tracks": ["inbound"],
    "customParameters": {
      "agentId": "123"
    }
  },
  "streamSid": "MZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Media Message (from Twilio):

{
  "event": "media",
  "sequenceNumber": "2",
  "media": {
    "track": "inbound",
    "chunk": "1",
    "timestamp": "5",
    "payload": "base64_encoded_mulaw_audio..."
  },
  "streamSid": "MZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Media Response (to Twilio):

{
  "event": "media",
  "streamSid": "MZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "media": {
    "payload": "base64_encoded_mulaw_audio..."
  }
}

Clear Buffer:

{
  "event": "clear",
  "streamSid": "MZxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Audio Specifications

Audio Conversion

Twilio uses μ-law encoding. Convert to/from Linear PCM:

// μ-law to Linear PCM
func mulawToLinear(mulaw byte) int16 {
    mulaw = ^mulaw
    sign := (mulaw & 0x80) >> 7
    exponent := (mulaw & 0x70) >> 4
    mantissa := mulaw & 0x0F

    sample := ((int16(mantissa) << 3) + 0x84) << exponent
    sample -= 0x84

    if sign == 1 {
        return -sample
    }
    return sample
}

Recording

Enable call recording in your TwiML or API call:

payload.Set("Record", "true")
payload.Set("RecordingStatusCallback", "https://your-domain.com/api/webhooks/telephony/twilio")

Status Webhooks

Configure status callback URL to receive call events:

POST /api/webhooks/telephony/twilio
Content-Type: application/x-www-form-urlencoded

CallSid=CAxxxxxxxxx&
CallStatus=completed&
Duration=120&
RecordingUrl=https://api.twilio.com/...

Pricing

Prices as of 2024. Check Twilio Pricing for current rates.

Troubleshooting

WebSocket Not Connecting

1. Verify your domain has valid SSL certificate
2. Check Twilio console for error logs
3. Ensure WebSocket endpoint is publicly accessible

Audio Quality Issues

1. Verify μ-law encoding/decoding is correct
2. Check for sample rate mismatches
3. Monitor WebSocket latency

Call Not Initiating

1. Verify Account SID and Auth Token
2. Check phone number format (E.164: +1234567890)
3. Ensure account has sufficient balance

Next Steps

• Exotel Integration - Alternative for India
• STT Configuration - Optimize speech recognition
• Latency Optimization - Reduce response time