Twilio

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

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
Local Development (ngrok)

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"
  }
}

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.

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.

Attach vault credential to the assistant

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

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

Getting Started

Dashboard (UI)

Web API

Assistant API

Integration API

Endpoint API

Document API

Vault Credentials

Setup

What Rapida Returns

Outbound Calls

Audio Spec

Vonage

Exotel

Telephony Overview

Configuration

​Vault Credentials

​Setup

​What Rapida Returns

​Outbound Calls

​Audio Spec

Vonage

Exotel

Telephony Overview

Configuration

Vault Credentials

Setup

What Rapida Returns

Outbound Calls

Audio Spec