Skip to main content

<Play>

Plays an audio file to the caller. Use for pre-recorded greetings, hold music, or dynamic audio files generated by your application.

Syntax​

<Play>https://your-cdn.example.com/audio/greeting.wav</Play>

The content of the <Play> element is the URL of the audio file to play.

Supported formats​

FormatRecommended spec
WAV8000 Hz, Mono, 16-bit PCM
MP38 kbps or higher

For best quality and lowest transcoding latency, use 8000 Hz Mono WAV.

Attributes​

AttributeRequiredDefaultDescription
loopNo1Number of times to repeat. 0 = repeat indefinitely

Inside Gather​

<Gather numDigits="1" action="https://your-app.example.com/ivr">
<Play>https://cdn.example.com/press-1-for-sales.wav</Play>
</Gather>

Example — greeting with fallback​

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Play>https://cdn.example.com/welcome.wav</Play>
<Gather numDigits="1" action="https://your-app.example.com/route" timeout="5">
<Play>https://cdn.example.com/ivr-menu.wav</Play>
</Gather>
<Hangup/>
</Response>

Legs API — StartPlay / StopPlay​

For mid-call audio playback on an active leg, use the Legs API actions:

# Play a file on an active leg
curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions/start_play' \
-H 'Content-Type: application/json' \
-d '{"url": "sound://https://cdn.example.com/hold-music.wav", "loop": -1}'

# Stop playback
curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions/stop_play'

Or using ExoML in a Legs API action:

curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions' \
-H 'Content-Type: application/json' \
-d '{
"exoml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Flow><StartPlay>sound://https://cdn.example.com/hold-music.wav</StartPlay></Flow>"
}'
note

In Legs API ExoML, the URL must have a sound:// prefix before the http:// or https:// URL: sound://https://cdn.example.com/audio.wav

Events emitted​

EventDescription
play_startedAudio playback has begun
play_completedAudio file played to completion
play_stoppedPlayback stopped early via stop_play

Best practices​

  • Host audio files on a CDN close to your callers (India: use a Mumbai-region CDN)
  • Keep file sizes under 2 MB to avoid delays
  • Use Exotel's recording URLs directly in <Play> to replay recorded messages