Skip to main content

ExoML

ExoML (Exotel Markup Language) is Exotel's event-driven call control API. Instead of building flows in the dashboard, you write code that responds to live call events and issues XML actions to control each call leg in real time.

How it works​

Your app creates a Leg via REST API
│
▼
Exotel dials the call
│
▼
Exotel POSTs event to your HTTPS endpoint (leg_ringing, leg_answered, …)
│
▼
Your endpoint returns HTTP 200 (ack)
│
▼
Your app calls POST /legs/{leg_sid}/actions with ExoML XML
│
▼
Exotel executes the action (play audio, gather DTMF, dial, record, …)
│
▼
Exotel POSTs the result event to your endpoint

Your HTTP response to Exotel is just an acknowledgement — return HTTP 200 immediately. The next call instruction is a separate REST API call you make after the ack, not the response body.

When to use ExoML vs dashboard applets​

RequirementUse
Dynamic IVR built from code / gitExoML
Leg-level control (hold one party, talk to another)ExoML
AI voicebot / streamingExoML
Simple fixed call flow, no code dependencyDashboard Applets
Click-to-call with a fixed IVRDashboard Applets + Voice V1

Base URL​

Data CenterBase URL
Singaporehttps://cpaas-api.exotel.com/v2/accounts/{account_sid}
Mumbaihttps://cpaas-api.in.exotel.com/v2/accounts/{account_sid}

Authentication​

HTTP Basic Authentication using your API key and token.

curl -u "<api_key>:<api_token>" \
-H "Content-Type: application/json" \
https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs

Get credentials from my.exotel.com → Developer Settings → API Settings.

Core resources​

ResourceEndpointDescription
LegPOST /legsCreate a call leg (outbound or inbound)
Leg actionsPOST /legs/{leg_sid}/actionsExecute an ExoML action on a leg
Leg detailsGET /legs/{leg_sid}Get leg state and metadata
BridgePOST /bridgesCreate a multi-party conference
Bridge actionsPOST /bridges/{bridge_sid}/actionsExecute an action on a bridge

ExoML action structure​

Every action request sends an ExoML XML string in the exoml field:

POST /v2/accounts/{account_sid}/legs/{leg_sid}/actions

{
"action_custom_param": "optional-tracking-value",
"exoml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Flow><Hangup></Hangup></Flow>"
}

The <Flow> element is the root wrapper. Inside it goes one action verb.

Available actions​

Leg actions

ActionVerbWhat it does
Play audio<StartPlay> / <StopPlay>Play a WAV/MP3 URL on the leg
Text-to-speech<StartSay> / <StopSay>Speak text using TTS (Polly or Google TTS)
Collect DTMF<Gather>Wait for keypad digits
Dial<Dial>Dial another number and bridge the legs
Record<StartRecording> / <StopRecording>Record the leg audio
Hold<Hold> / <UnHold>Put the leg on hold with music
Mute<Mute> / <Unmute>Mute/unmute audio direction
Join bridge<JoinBridge>Add this leg to a conference bridge
Leave bridge<LeaveBridge>Remove from conference bridge
Hang up<Hangup>End the leg
Stream<StartStream> / <StopStream>Pipe audio to a WebSocket (AI/transcription)

Bridge actions

ActionVerbWhat it does
Play to conference<StartPlay> / <StopPlay>Play audio to all bridge participants
TTS to conference<StartSay> / <StopSay>Speak text to all participants
Record conference<StartRecording> / <StopRecording>Record the full bridge

Events​

Exotel emits events to your HTTPS endpoint throughout the call lifecycle.

Leg lifecycle events (leg_lifecycle_event)

  • leg_connecting, leg_ringing, leg_answered, leg_terminated, leg_incoming

Leg action events (leg_action_event)

  • play_started, play_completed, play_interrupted, play_failed_to_start
  • gather_success, gather_failed, gather_interrupted
  • dial_initiated, dial_success, dial_completed, dial_failed
  • recording_started, recording_stopped, recording_available
  • hold_success, hold_failed

Next steps​