Connect to Flow (with Voice AI)

the connect to flow api lets you place an outbound call that is controlled by an exotel flow flows let you design complex call experiences — play messages, collect input, route to different outcomes — and can hand the caller off to a conversational ai bot at any point in the journey use this api when your call needs logic beyond a direct bot connection for example, playing a terms disclosure before connecting to a bot, or routing a caller to either a human agent or a bot based on their menu selection typical use cases multi step outbound ivrs with bot fallback, compliance driven call flows, blended human + ai workflows 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 flow built in the exotel dashboard if your flow includes a bot, it should have a voicebot or stream applet configured with your bot's websocket url how it works you send an api request with the caller's phone number and the url of an exotel flow exotel dials the phone number once the call is answered, the flow begins executing — playing audio, collecting dtmf, routing logic, etc when the flow reaches a voicebot or stream applet, exotel opens a websocket connection to your bot and streams audio in real time the bot can speak to the caller and, when done, hand back to the flow or end the call call status updates are sent to your configured callback url setting up your flow to include a bot in your flow, add one of the following applets in the exotel flow builder applet when to use voicebot connect the caller to an ai bot configure the websocket url inside the applet stream stream audio to a custom websocket endpoint for real time processing connect transfer the caller to a human agent (for bot to human handover) passthru pass call control to an external system mid flow the streamurl and streamtype for the bot are configured inside the applet — you do not pass them in the api request 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 url flow url http //my exotel com/{your sid}/exoml/start voice/{app id} the app/flow url of the exotel flow that will control this call find this in your flow settings in the dashboard optional parameter required type description calltype no string trans for transactional calls timelimit no integer max call duration in seconds max 14400 (4 hours) timeout no integer ring timeout in seconds statuscallback no string webhook url for call status updates statuscallbackevents no array terminal, answered, or both customfield no string metadata passed to the applet via passthru example request bash curl x post 'https //\<api key> \<api token>@api exotel com/v1/accounts/\<accountsid>/calls/connect' \ d 'from=+91xxxxxxxxxx' \ d 'callerid=0xxxxxxxxxx' \ d 'url=https //my exotel com/\<accountsid>/exoml/start voice/\<flow id>' \ d 'record=true' \ d 'statuscallback=https //your server com/callback' replace \<flow id> with the numeric id of your flow from the dashboard response a successful request returns a call object immediately use statuscallback to track the call as it progresses through the flow 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 status current state of the call recordingurl link to the recording after the call ends (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 common flow patterns ivr → bot handover design your flow with an ivr menu applet first, then connect the appropriate option to a voicebot applet callers navigate the menu, and the bot handles the selected intent bot → human handover place a voicebot applet early in the flow, followed by a connect or transfer applet the bot handles routine queries and escalates to a live agent when needed bot → passthru use a passthru applet after the voicebot applet to pass call control to your own telephony system for further handling bot with compliance disclosure start with a greeting applet to play a required disclosure, then move to the voicebot applet the caller hears the disclosure before the bot begins the conversation things to keep in mind your flow must be created and active in the exotel dashboard before making api calls the url parameter must point to a valid exotel appengine flow url custom external urls are not supported for this parameter the voicebot and stream applets must be configured inside the flow with the correct websocket url do not pass streamurl or streamtype directly in this api call recording, status callbacks, and custom fields work the same way as they do for regular outbound calls need help? learn how to build flows with the exotel flow builder guide configure your bot in a flow using the voicebot applet guide for a direct bot connection without a flow, see the connect to bot api contact support at hello\@exotel com