<Hold> / <UnHold>
Puts a call leg on hold (optionally with custom music) and resumes it. Used in agent-transfer and call-park scenarios.
Hold
Pauses the caller's audio. Optionally plays custom music while they wait.
# Hold with default silence
curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions/hold' \
-H 'Content-Type: application/json' \
-d '{}'
Hold with custom music on hold
Pass a StartPlay ExoML inside the Hold action to play audio during the hold:
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><Hold><StartPlay>sound://https://cdn.example.com/hold-music.wav</StartPlay></Hold></Flow>"
}'
Hold ExoML structure
<Hold>
<StartPlay>sound://https://cdn.example.com/hold-music.wav</StartPlay>
</Hold>
The inner <StartPlay> follows the same spec as the Play verb for Legs API.
UnHold
Resumes a held leg.
curl -u '<api_key>:<api_token>' -X POST \
'https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>/actions/unhold' \
-H 'Content-Type: application/json' \
-d '{}'
Events emitted
| Event | Description |
|---|---|
hold_started | Leg is now on hold |
hold_ended | Leg resumed from hold |
Common use case — warm transfer
- Agent A is talking to the customer
- Agent A puts the customer on hold (
Hold) - Agent A consults Agent B in a separate leg
- Agent A connects Agent B to the customer (
JoinBridge) - Customer comes off hold automatically when bridged
Customer Leg ──────────────── [Hold] ────── [JoinBridge] ──── Bridge ──► Agent B
Agent A Leg ── [Dial Agent B] ──────────────────────────────────────────────────
See Legs & Bridges API for the bridge flow.