Skip to main content

<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​

EventDescription
hold_startedLeg is now on hold
hold_endedLeg resumed from hold

Common use case — warm transfer​

  1. Agent A is talking to the customer
  2. Agent A puts the customer on hold (Hold)
  3. Agent A consults Agent B in a separate leg
  4. Agent A connects Agent B to the customer (JoinBridge)
  5. 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.