Phone Calls with Twilio

Connect a real phone number to your Voxray agent. Callers dial in over PSTN, Twilio bridges the call to your server via WebSocket, and your agent answers in real time.

What you’ll build

A Voxray server that accepts inbound phone calls routed through Twilio. When someone dials your Twilio number:

1. Twilio receives the PSTN call and sends a POST webhook to your server’s / endpoint
2. Voxray responds with TwiML XML that points Twilio to /telephony/ws
3. Twilio opens a WebSocket to /telephony/ws for bidirectional audio
4. Audio flows through the STT → LLM → TTS pipeline in real time
5. Voxray streams synthesised speech back; Twilio plays it to the caller

Audio format: Twilio sends G.711 μ-law at 8kHz. Voxray automatically upsamples to 16kHz before passing audio to the STT provider — no manual resampling needed.

Prerequisites

• Voxray binary built or downloaded
• A Twilio account with an active phone number and Voice capabilities enabled
• An AI provider account with API keys (this tutorial uses Groq — fast, free tier available)
• ngrok for local tunnelling (production deployments use a real public domain)

---

Steps

---

Audio characteristics and resampling

Twilio’s media stream delivers audio as G.711 μ-law encoded at 8kHz, which is the standard PSTN codec. Most STT providers expect 16kHz PCM.

Voxray’s Twilio serializer handles this automatically:

• Decodes μ-law bytes to 16-bit linear PCM
• Upsamples from 8kHz to 16kHz using linear interpolation
• Passes 16kHz PCM frames to the STT processor

No configuration is required. The upsampling is transparent; you will notice slightly reduced audio fidelity compared to a WebSocket client sending native 16kHz audio, which is inherent to the PSTN codec.

---

Production deployment

For production, replace ngrok with a server that has a stable public hostname and a valid TLS certificate.

Minimum production checklist:

1. Deploy Voxray on a VM or container with a public IP (or behind a load balancer)
2. Obtain a TLS certificate (e.g. via Let’s Encrypt / Certbot, or terminate TLS at your load balancer)
3. Point a domain name (e.g. voice.example.com) at your server
4. Set proxy_host in config.json to your domain:

{
  "runner_transport": "twilio",
  "proxy_host": "voice.example.com",
  ...
}

5. Update your Twilio phone number webhook to https://voice.example.com
6. Optionally set server_api_key in config and use Twilio’s request validation to verify webhook authenticity

Twilio requires the webhook endpoint to respond in under 15 seconds. Voxray responds immediately with TwiML (well under 1 second) so this limit is not a concern in practice.

---

Troubleshooting

Symptom	Cause	Fix
Twilio error 11200 (HTTP retrieval failure)	Webhook returned non-XML or timed out	Check Voxray is running and proxy_host matches your ngrok URL exactly; Twilio must receive text/xml
404 when Twilio POSTs to your URL	proxy_host has wrong value or includes https://	Set proxy_host to the bare hostname only: abc123.ngrok.io
Caller hears nothing / one-way audio	STT or TTS provider error	Check Voxray logs for provider errors; verify the API key is correct and has credits
Call connects but agent never speaks	LLM not responding	Confirm the model name is valid for the chosen provider; check for timeout errors in logs
connection refused in ngrok terminal	Voxray not running on port 8080	Start Voxray before placing a test call; verify port in config matches the ngrok tunnel port
ngrok tunnel URL changed	Restarted ngrok on free plan	Update proxy_host in config, restart Voxray, and update the Twilio webhook URL
Twilio error 13225 (no geographic permission)	Outbound or inbound region not enabled	Enable the caller’s region in Twilio Console → Voice → Settings → Geographic Permissions