Connect Voice AI API
The Connect 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://. |
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 | Any text you want attached to the call record (max 128 characters). Useful for tracking order IDs, customer IDs, etc. |
StatusCallback | A URL on your server that Exotel will call with updates when the call status changes. |
StatusCallbackEvents | Which events to receive: answered, terminal (call ended), or ringing. You can specify more than one. This is available only for leg1 |
StreamName | An optional label for the stream, up to 32 characters. |
Example Request
bash
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.
- Recording, status callbacks, and custom fields all work the same way as they do for regular outbound calls.
- 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].