Playback

Play audio files to active calls with full transport controls: start, stop, pause, resume, seek, restart, and silence. Also includes the composite play_and_get_digits command for DTMF collection.

All playback endpoints require App authentication via X-App-ID and X-API-Key headers. The session must exist and belong to your application.

Playback start

Start audio playback on a call. Files are fetched asynchronously via HTTP, then playback begins. If playback is already active, it is stopped first (last-wins semantics). Deferred command with a 2 s timeout.

Request body

Field	Type	Required	Description	Validations
`urls`	string[]	required	HTTP/HTTPS URLs of audio files to play.	Non-empty array. Each URL max 2048 chars. Max 128 files. Only `http://` and `https://`.
`offset_sec`	integer	optional	Seek offset in seconds to start playback from.	Range 0–86400. Not allowed with multiple URLs.

Rate limit — playback group, 500 ms cooldown per session. Shared with playback/silence.

POST /api/v1/sessions/{uuid}/commands/playback/start

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/start \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://cdn.example.com/greeting.wav", "https://cdn.example.com/menu.wav"]}'

Triggered webhooks

playback.started — deferred; fires after all file fetches complete.
playback.stopped — deferred; fires when playback finishes or is interrupted.
playback.file_not_found — fires on fetch failure or file-not-found.
command.result — deferred; fires on execute complete or 2 s timeout.

Playback stop

Stop active playback immediately. The command.result fires immediately. The interrupted playback produces a playback.stopped webhook with the original playback’s command_uid.

Request body — no additional fields beyond the optional command_uid.

Rate limit — seek group, 100 ms cooldown per session. Shared with pause, resume, seek, restart.

POST /api/v1/sessions/{uuid}/commands/playback/stop

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/stop \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Triggered webhooks

command.result — immediate.
playback.stopped — deferred; from the interrupted playback’s completion.

Playback pause

Pause active playback. The command.result fires immediately.

Request body — no additional fields beyond the optional command_uid.

Rate limit — seek group, 100 ms cooldown per session.

POST /api/v1/sessions/{uuid}/commands/playback/pause

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/pause \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Triggered webhooks

command.result — immediate.

Playback resume

Resume paused playback. The command.result fires immediately.

Request body — no additional fields beyond the optional command_uid.

Rate limit — seek group, 100 ms cooldown per session.

POST /api/v1/sessions/{uuid}/commands/playback/resume

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/resume \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Triggered webhooks

command.result — immediate.

Playback seek

Seek within active playback. Positive values seek forward, negative values seek backward.

Request body

Field	Type	Required	Description	Validations
`position_ms`	integer	required	Seek offset in milliseconds. Positive = forward, negative = backward.	Must be non-zero. Zero is rejected because it causes an unintended 1000 ms forward jump.

Rate limit — seek group, 100 ms cooldown per session.

POST /api/v1/sessions/{uuid}/commands/playback/seek

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/seek \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position_ms": 10000}'

Triggered webhooks

command.result — immediate.

Playback restart

Restart playback from the beginning. The command.result fires immediately.

Request body — no additional fields beyond the optional command_uid.

Rate limit — seek group, 100 ms cooldown per session.

POST /api/v1/sessions/{uuid}/commands/playback/restart

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/restart \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Triggered webhooks

command.result — immediate.

Playback silence

Stop any current playback and start an infinite silence stream. This keeps the channel alive without audio. The silence only ends on hangup. Deferred command with 2 s timeout.

Request body — no additional fields beyond the optional command_uid.

Rate limit — playback group, 500 ms cooldown per session. Shared with playback/start.

POST /api/v1/sessions/{uuid}/commands/playback/silence

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/playback/silence \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Triggered webhooks

playback.stopped — deferred; fires for any interrupted active playback, and for the silence stream itself on hangup.
command.result — deferred; fires on execute complete or 2 s timeout.

Play and get digits

Play an audio prompt and collect DTMF digits from the caller. A multi-phase composite command: prompt files are fetched first, then optional invalid-input files, then DTMF collection begins. Deferred command with 2 s timeout.

Request body

Field	Type	Required	Description	Validations
`prompt_files`	string[]	required	HTTP/HTTPS URLs for the prompt audio played to the caller.	Non-empty array. Max 128 files. Each a valid `http://`/`https://` URL.
`invalid_files`	string[]	optional	URLs played on invalid input. Falls back to 250 ms silence if omitted.	Max 128 files. Each a valid `http://`/`https://` URL.
`min_digits`	integer	optional	Minimum digits to collect. Default `1`.	Range 0–128. Must be ≤ `max_digits`.
`max_digits`	integer	optional	Maximum digits to collect. Default `10`.	Range 1–128.
`max_tries`	integer	optional	Maximum retry attempts. Default `3`.	Range 1–10. Total timeout (`timeout * max_tries`) ≤ 120000 ms.
`timeout`	integer	optional	Timeout per try in milliseconds. Default `5000`.	Range 1000–300000 ms. Total timeout ≤ 120000 ms.
`terminators`	string	optional	DTMF terminator characters. Default `#`.	Only `#` and `*` allowed. Max 16 chars.

Rate limit — heavy group, 2 s cooldown per session. Shared with record/start and record/stop.

POST /api/v1/sessions/{uuid}/commands/play_and_get_digits

curl -X POST https://gateway.example.com/api/v1/sessions/{uuid}/commands/play_and_get_digits \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_files": ["https://cdn.example.com/enter-pin.wav"], "invalid_files": ["https://cdn.example.com/invalid-pin.wav"], "min_digits": 4, "max_digits": 6, "max_tries": 3, "timeout": 10000, "terminators": "#"}'

Triggered webhooks

digits.collected — deferred; fires when DTMF collection finishes with collected digits, terminator, and status.
dtmf — individual DTMF digit events fire in real-time during collection.
playback.file_not_found — fires on fetch failure for prompt or invalid files.
command.result — deferred; fires on execute complete or 2 s timeout.

Error responses

Status	Condition
`400`	Invalid URLs, missing required fields, validation failures (e.g. `offset_ms` used, zero `position_ms`, total timeout exceeded).
`401`	Missing or invalid `X-API-Key`.
`403`	Session belongs to a different application.
`404`	Session not found.
`429`	Rate limit exceeded (global or per-command cooldown).