Connect Voice AI with Flow API
The Connect Voice AI to Flow API lets you place an outbound call that is controlled by an Exotel Flow. Flows let you design complex call experiences — bidirectional stream(Voice AI), unidirectional stream(Agent Assist), play messages, collect input, route to different outcomes — and can hand the caller off to a Agent 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 Voice AI calls with Agent or human 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:
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 App bazaar |
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
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
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
VoiceBot AppletBot → Passthru AppletPassthru →Programmable Connect: Working with Connect Applet (Dynamic URL)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 AppletPassthru Use a Passthru applet after the Voicebot applet to pass call control to your own telephony system for further handling.
IVR → VoiceBot AppletBot 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 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 [email protected].