Connect Voice AI API
The Connect voice to Bot API lets you programmatically call a phone number and connect the call to a conversational AI bot in real time. Audio flows in both directions — the caller speaks to the bot, and the bot responds to the caller — over a secure WebSocket connection.
Typical use cases: AI-powered outbound campaigns, virtual customer care agents, automated surveys, and appointment reminders with live confirmation.
Before You Start
You will need:
- Your Exotel Account SID, API Key, and API Token (available from your Exotel Dashboard).
- An ExoPhone (virtual number) to use as the Caller ID.
- A WebSocket server endpoint (your bot service) that accepts audio in real time.
How It Works
- You send an API request with the caller's phone number and your bot's WebSocket URL.
- Exotel dials the phone number.
- Once the call is answered, Exotel opens a connection to your WebSocket server.
- Audio is streamed live between the caller and your bot for the duration of the call.
- When the call ends (by either party), Exotel sends a status update to your callback URL.
API Reference
Endpoint:
Base URLs:
Region | Base URL |
|---|---|
Singapore | https://api.exotel.com |
Mumbai | https://api.in.exotel.com |
Authentication uses HTTP Basic Auth with your API Key as the username and API Token as the password.
Parameters
Required
Parameter | Description |
|---|---|
From | The phone number to call. Use international format (e.g., +919876543210). |
CallerId | Your Exotel virtual number that appears as the caller ID. |
StreamUrl | The WebSocket URL of your bot server. Must start with ws:// or wss://. max length 600 (STREAM_URL_MAX_LENGTH), including query string. |
StreamType | Set this to bidirectional to enable two-way audio. |
Optional
Parameter | Description |
|---|---|
Record | Set to true to record the call. Default: false. |
RecordingChannels | single (merged) or dual (separate track per side). Default: single. |
TimeLimit | Maximum call duration in seconds. Up to 14,400 (4 hours). |
CustomField | CustomField | Opaque string on the call (max 128 characters). Returned on event StatusCallbacks when you use StatusCallbackEvents. Not sent to the bot as start.custom_parameters — put bot keys on the StreamUrl query string. |
StatusCallback | A POST HTTPS URL on your server that Exotel will call with updates when the call status changes. |
StatusCallbackEvents | StatusCallbackEvents | answered, terminal, and/or ringing. Send as StatusCallbackEvents[]=terminal. Needed for CustomField / DisconnectedBy on the webhook. Without it, StatusCallback is a thin payload (no CustomField). See |
StreamName | An optional label for the stream, up to 32 characters. |
Example Request
bash
curl -u '<api_key>:<api_token>' -X POST \
'https://api.in.exotel.com/v1/Accounts/<AccountSid>/Calls/connect' \
-F 'From=+91XXXXXXXXXX' \
-F 'CallerId=0XXXXXXXXXX' \
-F 'StreamUrl=wss://your-bot.example.com/media?campaign_id=C123' \
-F 'StreamType=bidirectional' \
-F 'CustomField={"campaign_id":"C123"}' \
-F 'Record=true' \
-F 'StatusCallback=https://your-server.com/callback' \
-F 'StatusCallbackEvents[]=terminal' \
-F 'StatusCallbackContentType=application/json'Response
A successful request returns a Call object immediately. The call is still being set up at this point — use StatusCallback to track when the call is answered and when it ends.
json
Field | What it means |
|---|---|
Sid | A unique ID for this call. Save it to look up call details later. |
Status | Current state of the call. |
From | The number that was dialed. |
RecordingUrl | Link to the recording once the call is complete (if recording was enabled). |
Call status values:
Status | Meaning |
|---|---|
queued | Call is being prepared. |
in-progress | Call is active. |
completed | Call ended normally. |
failed | Call could not be placed. |
busy | The number was busy. |
no-answer | The number did not answer. |
Configuring Your Bot's WebSocket Server
Your bot must accept a WebSocket connection and handle audio in real time. Key points:
- Exotel sends audio as raw PCM or mulaw at 8 kHz by default. To request a different sample rate, append it to your StreamUrl: wss://your-bot.example.com/media?sample-rate=16000. Supported values: 8000, 16000, 24000.
- Your bot can send audio back to the caller at any time during the call.
- When your bot wants to end the call, it closes the WebSocket connection.
For full protocol details, see the AgentStream documentation.
Things to Keep in Mind
- StreamUrl must use ws:// or wss://. Plain HTTP URLs are not supported.
- The full StreamUrl (including any query string) must be under 600 characters.
- If you provide a StreamName, it must be 32 characters or fewer.
- Query parameters on StreamUrl are how you pass custom data into the bot (start.custom_parameters). Prefer this over StreamCustomField.
- https:// is not valid as StreamUrl. Resolve any HTTPS discovery URL yourself, then pass wss://… (with your query params on that WSS URL).
- StatusCallbackEvents work on Connect Voice AI. They are not accepted with a flow Url (…/exoml/start_voice/{app_id}) — API returns 400.
- Webhook fields (CustomField, DisconnectedBy, outcomes): StatusCallbackStatusCallback.
- This feature must be enabled on your account before use. Contact [email protected] to get started.
Need Help?
- Read the AgentStream guide to understand how Exotel streams audio to your bot.
- For API errors and response codes, see the Error Code Reference.
- Contact support at [email protected].