Playback events

Playback events track audio playback on active calls, including start, completion, and error states. The command.result event provides an additional confirmation of command success or failure.

playback.started

Fired when the call leg actually begins playing the requested audio — the moment the gateway reports that the playback application has started executing on the channel, after URL fetch and decoding. Receipt of playback.started means audio is now reaching the caller.

Payload schema

Field	Type	Description
`event`	string	Always `"playback.started"`. required
`session_uuid`	string	Unique session identifier. required
`command_uid`	string	The `command_uid` from the `playback/start` request. required
`urls`	string[]	The original URL(s) from the API request, as an array. Single-URL playbacks emit a one-element array. Matches the shape used by `conference.play.*` events. required
`file_path`	string	deprecated The original URL(s) joined with `,`. Retained for two releases for backward compatibility — new consumers should read `urls` instead.

{
  "event": "playback.started",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "play-greeting-001",
  "urls": ["https://cdn.example.com/audio/greeting.wav"],
  "file_path": "https://cdn.example.com/audio/greeting.wav"
}

playback.stopped

Fired when playback completes normally (reaches the end of the file) or is stopped via the playback/stop command. The offset_ms field indicates where playback was when it ended.

Payload schema

Field	Type	Description
`event`	string	Always `"playback.stopped"`. required
`session_uuid`	string	Unique session identifier. required
`command_uid`	string	The `command_uid` from the `playback/start` request. required
`urls`	string[]	The original URL(s) from the API request, as an array. required
`file_path`	string	deprecated The original URL(s) joined with `,`. Read `urls` instead.
`offset_ms`	integer	Playback position at stop time in milliseconds. required
`duration_ms`	integer	Total playback duration in milliseconds. required

{
  "event": "playback.stopped",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "play-greeting-001",
  "urls": ["https://cdn.example.com/audio/greeting.wav"],
  "file_path": "https://cdn.example.com/audio/greeting.wav",
  "offset_ms": 15230,
  "duration_ms": 15230
}

playback.file_not_found

Fired when an audio file cannot be found or fetched. This can occur during the HTTP file fetch phase or during playback execution. Applies to both playback/start and play_and_get_digits commands.

Payload schema

Field	Type	Description
`event`	string	Always `"playback.file_not_found"`. required
`session_uuid`	string	Unique session identifier. required
`command_uid`	string	The `command_uid` from the `playback/start` or `play_and_get_digits` request. required
`urls`	string[]	The original URL(s) that failed, as an array. required
`file_path`	string	deprecated The original URL(s) joined with `,`. Read `urls` instead.

{
  "event": "playback.file_not_found",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "command_uid": "play-greeting-001",
  "urls": ["https://cdn.example.com/audio/missing.wav"],
  "file_path": "https://cdn.example.com/audio/missing.wav"
}

command.result

Reports the outcome of an asynchronous command. For fire-and-forget commands (hangup, disconnect, playback/stop, etc.), this is published immediately. For deferred commands (answer, playback/start, play_and_get_digits), it is published after the operation completes or after a 2-second timeout.

Payload schema

Field	Type	Description
`event`	string	Always `"command.result"`. required
`session_uuid`	string	Unique session identifier. required
`operation_id`	string	UUID matching the `operation_id` from the `202 Accepted` HTTP response. required
`command`	string	The command type (e.g. `call.answer`, `playback.start`, `play_and_get_digits`). required
`command_uid`	string	The `command_uid` from the original API request. required
`success`	boolean	`true` if the command completed successfully, `false` on failure or timeout. required

Example — success:

{
  "event": "command.result",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "operation_id": "b3d1c8a0-7e2f-4a91-9c3e-1a2b3c4d5e6f",
  "command": "playback.start",
  "command_uid": "play-greeting-001",
  "success": true
}

Example — timeout:

{
  "event": "command.result",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "operation_id": "b3d1c8a0-7e2f-4a91-9c3e-1a2b3c4d5e6f",
  "command": "call.answer",
  "command_uid": "my-answer-cmd-001",
  "success": false
}

Triggered by

These events are produced by the following endpoints:

playback.started — playback/start.
playback.stopped — playback/start (on completion), playback/stop, playback/silence.
playback.file_not_found — playback/start, play_and_get_digits.
command.result — all playback commands.