Twilio

Run assistant-api with Twilio for global PSTN voice calls using WebSocket Media Streams.

Twilio sends a webhook when a call arrives. Rapida responds with TwiML that opens a bidirectional Media Stream (WebSocket) carrying μ-law 8kHz audio.

---

Vault Credentials

In the Rapida dashboard go to Credentials → Create Credential, select provider type Twilio:

Key	Description
account_sid	Twilio Account SID (ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
account_token	Twilio Auth Token

---

Setup

1. Set PUBLIC_ASSISTANT_HOST

   PUBLIC_ASSISTANT_HOST is the public HTTPS hostname Twilio will use to reach your server — for webhooks and the WebSocket media stream.

   Production

   Set it to your server’s public domain in docker/assistant-api/.assistant.env:

   PUBLIC_ASSISTANT_HOST=your-server.com   # no https:// prefix
   

   Also update connection.media in ui/src/configs/config.production.json:

   {
     "connection": {
       "media": "https://your-server.com"
     }
   }
   

   Local Development (ngrok)

   Twilio’s servers cannot reach localhost. Use ngrok to create a public HTTPS tunnel:

   1. Install and authenticate ngrok

   # macOS
   brew install ngrok/ngrok/ngrok
   
   # Linux
   curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
     | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
   echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
     | sudo tee /etc/apt/sources.list.d/ngrok.list
   sudo apt update && sudo apt install ngrok
   
   ngrok config add-authtoken <your-authtoken>
   

   Get your authtoken at dashboard.ngrok.com.

   2. Start the tunnel (keep this running)

   ngrok http 8080
   # Forwarding  https://abc123.ngrok-free.app -> http://localhost:8080
   

   3. Update two files with the ngrok hostname

   File	Field	Value
   docker/assistant-api/.assistant.env	PUBLIC_ASSISTANT_HOST	abc123.ngrok-free.app (no https://)
   ui/src/configs/config.development.json	connection.media	https://abc123.ngrok-free.app (with https://)

   # docker/assistant-api/.assistant.env
   PUBLIC_ASSISTANT_HOST=abc123.ngrok-free.app
   

   // ui/src/configs/config.development.json
   {
     "connection": {
       "media": "https://abc123.ngrok-free.app"
     }
   }
   

   4. Rebuild

   make rebuild-assistant
   

   The free ngrok tier generates a new URL on every restart. When it changes, update both files above and re-run make rebuild-assistant. Use a free static domain (ngrok http --domain=your-name.ngrok-free.app 8080) to avoid this.

2. Configure the Twilio phone number webhook

   In Twilio Console → Phone Numbers → Manage → Active numbers, select your number:

   Field	Value
   A call comes in	Webhook, HTTP POST
   URL	https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/call/{assistantId}?x-api-key={apiKey}
   Status callback URL	https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}/event?x-api-key={apiKey}

   Replace {assistantId} with the numeric assistant ID from the Rapida dashboard.

3. Attach vault credential to the assistant

   In the assistant’s Phone Deployment, select the Twilio vault credential you created.

4. Verify

   # Check the tunnel is proxying correctly
   curl https://{PUBLIC_ASSISTANT_HOST}/readiness/
   # Expected: {"status":"ok"}
   

   You can monitor Twilio webhook requests in real time at http://localhost:4040 (ngrok inspector) or in the Twilio Console under Monitor → Logs → Calls.

PUBLIC_ASSISTANT_HOST must be HTTPS. Twilio rejects plain HTTP webhook URLs and ws:// WebSocket connections — always use https:// for the webhook URL and wss:// for the media stream (Rapida handles this automatically).

---

What Rapida Returns

When Twilio hits the inbound webhook, Rapida responds with TwiML connecting a Media Stream:

<Response>
  <Connect>
    <Stream url="wss://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}?x-api-key={apiKey}"
            name="{assistantId}__{conversationId}"
            statusCallback="https://{PUBLIC_ASSISTANT_HOST}/v1/talk/twilio/ctx/{contextId}/event?x-api-key={apiKey}"
            statusCallbackEvent="initiated ringing answered completed">
      <Parameter name="assistant_id" value="{assistantId}"/>
      <Parameter name="client_number" value="{callerNumber}"/>
    </Stream>
  </Connect>
</Response>

---

Outbound Calls

Rapida calls client.Api.CreateCall via the Twilio Go SDK. The StatusCallback, StatusCallbackEvent, and Twiml are constructed automatically from PUBLIC_ASSISTANT_HOST. No additional configuration is required beyond the vault credential.

---

Audio Spec

Property	Value
Encoding	μ-law (PCMU) 8-bit
Sample rate	8000 Hz
Channels	Mono
Transport	Base64-encoded JSON frames (Media Streams spec)

---

Vonage

Global PSTN alternative with higher audio quality

Exotel

India / SEA PSTN

Telephony Overview

All providers and URL routing reference

Configuration

Full env var reference