<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
| Format | Recommended spec |
|---|---|
| WAV | 8000 Hz, Mono, 16-bit PCM |
| MP3 | 8 kbps or higher |
For best quality and lowest transcoding latency, use 8000 Hz Mono WAV.
Attributes
| Attribute | Required | Default | Description |
|---|---|---|---|
loop | No | 1 | Number 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
| Event | Description |
|---|---|
play_started | Audio playback has begun |
play_completed | Audio file played to completion |
play_stopped | Playback 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