Skip to main content

ExoML Action Reference

Every action is a POST to /v2/accounts/{account_sid}/legs/{leg_sid}/actions with an exoml field containing an XML string wrapped in <Flow>.

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

The action_custom_param value is echoed back in the resulting event under action_custom_parameter.


Play audio — <StartPlay> / <StopPlay>​

Plays a WAV or MP3 file from a URL on the leg.

<StartPlay> attributes​

AttributeRequiredTypeDefaultDescription
loopOptionalinteger0 (infinite)Times to repeat. Max 10.
usernameOptionalstring—Basic auth username for HTTPS URLs
passwordOptionalstring—Basic auth password for HTTPS URLs
(inner text)RequiredURL—File URL to play. Use prefix sound: for Exotel default sounds.

Examples​

<!-- Play a WAV from an HTTPS URL -->
<Flow>
<StartPlay username="abc123" password="securepass">
https://cdn.example.com/audio.wav
</StartPlay>
</Flow>

<!-- Stop current playback -->
<Flow><StopPlay></StopPlay></Flow>

Events​

Event nameDescription
play_startedPlayback started
play_completedFile fully played
play_interruptedStopped by another action
play_failed_to_startFile could not be fetched or played

Text-to-speech — <StartSay> / <StopSay>​

Converts text to speech and plays it on the leg. Supports Polly and Google TTS engines.

<StartSay> attributes​

AttributeRequiredTypeDefaultDescription
loopOptionalinteger0 (infinite)Times to repeat. Max 10.
preferredTTSEngineOptionalpolly | googlettspollyTTS engine
languageOptionalstringenLanguage code. All regional languages supported.
pollyVoiceIdOptionalstringRaveenaPolly voice ID. See AWS Polly voices.
googlettsVoiceNameOptionalstringssml gender femaleGoogle TTS voice name
(inner text)Requiredstring—Text or SSML markup to speak

Examples​

<!-- Plain text with Polly -->
<Flow>
<StartSay language="en" preferredTTSEngine="polly" pollyVoiceId="Aditi">
Welcome. Press 1 for sales, 2 for support.
</StartSay>
</Flow>

<!-- SSML with Google TTS -->
<Flow>
<StartSay preferredTTSEngine="googletts" language="en">
<speak>Your order <say-as interpret-as="digits">1234</say-as> is ready.</speak>
</StartSay>
</Flow>

<!-- Stop TTS -->
<Flow><StopSay></StopSay></Flow>

Events​

Event nameDescription
say_completedTTS finished playing
say_failed_to_startTTS could not be started

Play + Say sequence (<PlaySequence>)​

Play an audio file followed by a TTS message in a single action:

<Flow>
<PlaySequence>
<StartPlay>https://exotel.s3.mum-1.amazonaws.com/hold-music.wav</StartPlay>
<Say>This is spoken quickly.</Say>
</PlaySequence>
</Flow>

Collect DTMF — <Gather>​

Waits for the caller to press keypad digits.

<Gather> attributes​

AttributeRequiredTypeDescription
numDigitsOptionalintegerStop collecting after this many digits
timeoutInSecOptionalintegerSeconds to wait for input after the last digit
finishOnKeyOptionalstringKey that ends collection (e.g. #, *)

Examples​

<!-- Collect up to 5 digits, finish on * -->
<Flow>
<Gather numDigits="5" timeoutInSec="30" finishOnKey="*"></Gather>
</Flow>

<!-- Play audio while gathering -->
<Flow>
<Gather numDigits="1" timeoutInSec="10">
<StartPlay>https://example.com/ivr-prompt.wav</StartPlay>
</Gather>
</Flow>

Events​

Event nameDescription
gather_initiatedGather started
gather_startedFirst digit received
gather_successCompleted. event_data.data.digits contains the collected digits
gather_failedTimed out or error
gather_interruptedLeg hung up during gather

Dial another number — <Dial>​

Dials a second phone number and bridges both legs together.

<Dial> attributes​

AttributeRequiredTypeDefaultDescription
contactUriRequiredstring—Phone number (with country code) or SIP URI to dial
exophoneRequiredstring—Caller ID (ExoPhone virtual number)
networkTypeOptionalpstn | voippstnNetwork type
timeoutOptionalinteger (seconds)30Total timeout
ringTimeoutOptionalinteger (seconds)30Ring timeout before giving up
timeLimitOptionalinteger (seconds)14400Max call duration
absorbDtmfOptionalbooleanfalseIf true, DTMF tones from this leg are not passed to the bridge
customParamOptionalstring—Echoed in dial events

Example​

<Flow>
<Dial
contactUri="+91XXXXXXXXXX"
exophone="+91YYYYYYYYYY"
networkType="pstn"
absorbDtmf="true">
</Dial>
</Flow>

Events​

Event nameDescription
dial_initiatedDial started. event_data.data includes bridge_sid and second_leg_sid
dial_successSecond leg answered and bridged
dial_completedEither leg hung up or left the bridge
dial_failedCould not connect

Record — <StartRecording> / <StopRecording>​

Records audio on a leg.

<StartRecording> attributes​

AttributeRequiredTypeDefaultDescription
directionOptionalin | out | bothbothWhich audio stream to record
formatOptionalwav | mp3mp3Recording format
bitrateOptional8 | 24 | 32 | 64 | 1288Bitrate (kbps)
channelOptionalmono | stereomonoStereo only available when direction=both
storageTypeOptionals3 | httpss3Where to store the recording
storageURLRequired if storageType=httpsstring—HTTPS upload endpoint
storageURLKeyRequired if storageType=httpsstring—Basic auth key for the upload endpoint
storageURLTokenRequired if storageType=httpsstring—Basic auth token for the upload endpoint

Examples​

<!-- Record to Exotel S3 -->
<Flow>
<StartRecording direction="both" format="wav" storageType="s3"></StartRecording>
</Flow>

<!-- Record to your own server -->
<Flow>
<StartRecording
direction="both"
format="wav"
storageType="https"
storageURLKey="mykey"
storageURLToken="mytoken"
storageURL="https://recordings.example.com/upload">
</StartRecording>
</Flow>

<!-- Stop recording -->
<Flow><StopRecording></StopRecording></Flow>

Events​

Event nameDescription
recording_startedRecording began
recording_stoppedRecording stopped
recording_availableFile is ready. event_data.data.recording_sid contains the ID

Hold / Unhold — <Hold> / <UnHold>​

Puts the leg on hold with music-on-hold (MOH).

Examples​

<!-- Hold with Exotel default MOH -->
<Flow><Hold></Hold></Flow>

<!-- Hold with custom MOH audio -->
<Flow>
<Hold>
<StartPlay>https://exotel.s3.mum-1.amazonaws.com/hold-music.wav</StartPlay>
</Hold>
</Flow>

<!-- Unhold -->
<Flow><UnHold></UnHold></Flow>

Events​

Event nameDescription
hold_successLeg is on hold
hold_failedHold failed
unhold_successLeg resumed from hold
unhold_failedUnhold failed

Mute / Unmute — <Mute> / <Unmute>​

Mutes a specific audio direction on the leg.

<Mute> attributes​

AttributeRequiredTypeDescription
directionOptionalin | out | bothAudio direction to mute. Default: both

Examples​

<!-- Mute caller's microphone -->
<Flow><Mute direction="in"></Mute></Flow>

<!-- Unmute -->
<Flow><Unmute></Unmute></Flow>

Hang up — <Hangup>​

Ends the leg.

<Flow><Hangup></Hangup></Flow>

Events​

Event nameDescription
leg_terminatedLeg ended. event_data.data includes hangup_cause_code and sip_cause_code
hangup_failedHangup action failed

Join / Leave bridge — <JoinBridge> / <LeaveBridge>​

Adds or removes a leg from a conference bridge.

<JoinBridge> attributes​

AttributeRequiredTypeDescription
bridgeSidRequiredstringThe SID of the target bridge
absorbDtmfOptionalbooleanIf true, DTMF from this leg is absorbed

Examples​

<!-- Join a bridge -->
<Flow>
<JoinBridge bridgeSid="2NRbUtE18WNlhtNeK03wncca9Po00000" absorbDtmf="true">
</JoinBridge>
</Flow>

<!-- Leave the bridge -->
<Flow><LeaveBridge></LeaveBridge></Flow>

Stream audio — <StartStream> / <StopStream>​

Pipes real-time audio from the leg to a WebSocket server for AI processing or live transcription.

<!-- Start streaming to your WebSocket server -->
<Flow>
<StartStream url="wss://ai.example.com/stream" streamType="bidirectional" contentType="audio/x-mulaw;rate=8000"></StartStream>
</Flow>

<!-- Stop streaming -->
<Flow><StopStream></StopStream></Flow>

For the full streaming protocol and message format, see AgentStream.


Bridge actions​

Bridge actions target the whole conference rather than a single leg.

POST /v2/accounts/{account_sid}/bridges/{bridge_sid}/actions

Play / Say on bridge​

Same <StartPlay>, <StopPlay>, <StartSay>, <StopSay> syntax as leg actions. Audio plays to all participants.

Record bridge​

Same <StartRecording> / <StopRecording> syntax. Records the full mixed audio.

Warm transfer — <Refer>​

Transfers a bridge participant to another number while keeping the remaining participants connected.

<Flow>
<Refer contactUri="+91XXXXXXXXXX" exophone="+91YYYYYYYYYY"></Refer>
</Flow>