Vonage

Run assistant-api with Vonage (Nexmo) for global PSTN voice calls using WebSocket and NCCO.

Vonage sends a webhook when a call arrives. Rapida responds with an NCCO (Nexmo Call Control Object) that opens a WebSocket carrying Linear PCM 16kHz audio — higher quality than Twilio’s μ-law.

---

Vault Credentials

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

Key	Description
api_key	Vonage API key
api_secret	Vonage API secret
application_id	Vonage Application ID (required for JWT auth on outbound)
private_key	Vonage Application private key — PEM string (required for JWT auth on outbound)

---

Setup

1. Set PUBLIC_ASSISTANT_HOST

   PUBLIC_ASSISTANT_HOST is the public HTTPS hostname Vonage will use to reach your server — for the answer URL and the WebSocket media stream.

   Production

   Set it 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)

   Vonage’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. Use a free static domain (ngrok http --domain=your-name.ngrok-free.app 8080) so you only need to update Vonage’s answer URL once.

2. Create a Vonage Voice Application

   In Vonage Dashboard → Applications → Create a new application, enable Voice capability and set:

   Field	Value
   Answer URL (POST)	https://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/call/{assistantId}?x-api-key={apiKey}
   Event URL (POST)	https://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/ctx/{contextId}/event?x-api-key={apiKey}

   Click Generate public and private key — download the private key and store the PEM content in the vault credential’s private_key field.

3. Link a Vonage number

   In Numbers, assign a virtual number to the application you just created.

4. Attach vault credential to the assistant

   In the assistant’s Phone Deployment, select the Vonage vault credential.

5. Verify

   curl https://{PUBLIC_ASSISTANT_HOST}/readiness/
   # Expected: {"status":"ok"}
   

---

What Rapida Returns

When Vonage hits the answer URL, Rapida responds with an NCCO:

[{
  "action": "connect",
  "endpoint": [{
    "type": "websocket",
    "uri": "wss://{PUBLIC_ASSISTANT_HOST}/v1/talk/vonage/ctx/{contextId}?x-api-key={apiKey}",
    "content-type": "audio/l16;rate=16000"
  }]
}]

---

Audio Spec

Property	Value
Encoding	Linear PCM 16-bit
Sample rate	16000 Hz
Channels	Mono
Transport	Raw binary WebSocket frames

16kHz Linear PCM improves STT accuracy over 8kHz μ-law (Twilio/Exotel), particularly for providers that natively support 16kHz input.

---

Twilio

Alternative global PSTN provider

Exotel

India / SEA PSTN

Telephony Overview

All providers and URL routing reference

Configuration

Full env var reference