--- title: Connect Voice AI API slug: voice-apis/connect-voice-ai-api createdAt: 2026-08-10T11:58:41.994Z --- 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 1. You send an API request with the caller's phone number and your bot's WebSocket URL. 2. Exotel dials the phone number. 3. Once the call is answered, Exotel opens a connection to your WebSocket server. 4. Audio is streamed live between the caller and your bot for the duration of the call. 5. When the call ends (by either party), Exotel sends a status update to your callback URL. ## API Reference **Endpoint:** :::BlockQuote POST /v1/Accounts/{AccountSid}/Calls/connect ::: **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 :::BlockQuote curl -X POST 'https\://\:\@api.exotel.com/v1/Accounts/\/Calls/connect' \ -F 'StreamType=bidirectional' \ -F 'StreamUrl=wss\://your-bot.example.com/media' \ -F 'From=+91XXXXXXXXXX' \ -F 'CallerId=0XXXXXXXXXX' \ -F 'Record=true' \ -F 'StatusCallback=https\://your-server.com/callback' \ -F 'StatusCallbackEvents\[]=terminal' ::: ### 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 :::BlockQuote \{ "Call": \{ "Sid": "a1b2c3d4e5f6...", "Status": "in-progress", "From": "+91XXXXXXXXXX", "PhoneNumberSid": "0XXXXXXXXXX", "Direction": "outbound-api", "DateCreated": "2025-06-01 10:00:00", "RecordingUrl": null }} ::: | 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 hello\@exotel.com 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 hello\@exotel.com.