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 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 curl x post 'https //\<api key> \<api token>@api exotel com/v1/accounts/\<accountsid>/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 { "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