Twilio
Set up Twilio as your telephony provider for outbound and inbound voice calls with zoxaAI.
What you'll learn
How to configure Twilio as a telephony provider in zoxaAI, including finding your credentials, setting up inbound webhooks, and understanding Twilio-specific features like call transfer support and signature verification.
Twilio
Twilio is a cloud communications platform that provides programmable voice APIs. zoxaAI integrates with Twilio for both outbound and inbound calling via Twilio Media Streams.
Provider Details
| Feature | Value |
|---|---|
| Provider name | twilio |
| Audio format | mulaw |
| Sample rate | 8,000 Hz |
| Call transfer | Yes |
| Auto-create application | No |
| Webhook signature verification | Yes (HMAC-SHA1) |
| Account ID field | account_sid |
Prerequisites
- A Twilio account (sign up at twilio.com)
- At least one Twilio phone number purchased in your account
Credentials
You need two values from your Twilio Console:
| Field | Where to Find It | Sensitive | Description |
|---|---|---|---|
| Account SID | Twilio Console dashboard (top of page) | Yes | Your unique account identifier. Starts with AC. |
| Auth Token | Twilio Console dashboard (click "Show" next to Auth Token) | Yes | Your account's secret authentication token. Used for API authentication and webhook signature verification. |
Setup
Open the Telephony Page
Navigate to Telephony in the zoxaAI sidebar.
Add a New Configuration
Click Add Configuration. Select Twilio from the provider dropdown.
Enter Your Credentials
Paste your Account SID and Auth Token from the Twilio Console.
Name the Configuration
Give it a descriptive name, such as "Twilio US Production" or "Twilio Testing".
Save
Click Save. The configuration is created and your credentials are stored securely (masked in the UI after save).
Add Phone Numbers
Right after you save, zoxaAI opens the new configuration and fetches the voice numbers on your Twilio account. Click Add next to the ones you want, or Add all. You can fetch again any time with Fetch from Twilio in the Phone Numbers section.
To add a number by hand instead, click Add phone number and enter it in E.164 format:
+14155552671
+12125551234Only voice-capable numbers are listed, and each number's Twilio friendly name is filled in as its label. These numbers are used as caller IDs for outbound calls and for inbound routing.
Outbound Calls
Once configured, Twilio can place outbound calls from:
| Source | Description |
|---|---|
| Test calls | Place a test call from the agent editor in the dashboard |
| API calls | Use POST /api/v1/call with your API key |
| Campaigns | Bulk outbound dialing across a contact list |
Twilio handles call initiation via its REST API. When the call is answered, audio is streamed bidirectionally over WebSocket using Twilio Media Streams in audio/x-mulaw;rate=8000 format.
Inbound Calls
Twilio fully supports inbound calling. To receive inbound calls, you need to point your Twilio phone number's voice webhook to zoxaAI.
Open Twilio Console
Go to the Twilio Console and navigate to Phone Numbers > Manage > Active Numbers.
Select the Phone Number
Click the phone number you want to receive inbound calls on.
Configure Voice Webhook
Under Voice Configuration, set:
- A call comes in: Webhook
- URL:
https://your-domain.com/api/v1/telephony/run - HTTP Method: POST
Replace your-domain.com with your zoxaAI deployment URL.
Assign an Agent
Back in the zoxaAI dashboard, go to Telephony > your Twilio configuration and open the phone number (or add it). Select the agent that should answer in the Inbound target dropdown and save. You can also bind the number to an agent through the API with POST /api/v1/call and type: "inbound".
See Inbound Calling for the full inbound routing guide.
Call Transfer
Twilio is one of the providers that supports call transfer. When an agent invokes the Call Transfer tool, zoxaAI uses Twilio's conference-based transfer mechanism to connect the caller to a human agent or another phone number.
Signature Verification
zoxaAI automatically verifies Twilio webhook signatures on every inbound webhook request using your stored Auth Token. This ensures that inbound webhook requests genuinely originate from Twilio and have not been tampered with.
No additional setup is required -- verification happens automatically as long as your Auth Token is correctly configured.
Keep your Auth Token current
If you rotate your Auth Token in the Twilio Console, update it in your zoxaAI telephony configuration immediately. Mismatched tokens will cause inbound call routing to fail with a signature verification error.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Outbound calls fail with "not configured" | No default telephony configuration set | Set your Twilio configuration as the default on the Telephony page |
| Inbound calls not routing | Webhook URL not set in Twilio Console | Configure the voice webhook URL as described above |
| Signature verification fails | Auth Token mismatch between Twilio and zoxaAI | Update the Auth Token in your zoxaAI configuration to match the Twilio Console |
| "No phone numbers configured" | No numbers added to the configuration | Add at least one phone number in E.164 format |