Start audio playback

Rate limit: Per command · Burst: 8 · Refill: 4 req/s

Play WAV or MP3 files, live AAC/HLS streams, raw live audio, or indefinite silence.

Playback modes:

• Use type: files for one or more WAV or MP3 files.
• Use type: silence for indefinite silence.
• Use type: stream with one HTTP/HTTPS AAC or HLS live stream url; optionally set format to aac or hls, or omit it for auto-detection. Explicit ports must be 80 or 443. Playback starts at the current live position and does not support pause, resume, or seek.
• Use type: push with a raw mono media_format. The 202 response includes an ingest object with the short-lived URL, HTTP method, required headers, and expiry. Send one streaming POST exactly as described, add the normal Bearer authorization header in addition to ingest.headers, write unframed raw audio in the request body, and close the body at end of input. A successful ingest response means the complete body was accepted, not that the caller has heard all audio.

File playlists play in URL order. Session playback does not loop. To start partway through one file, set offset_ms; an offset is not valid for a playlist.

A new play request automatically replaces active playback. Call playback/stop to stop audio without starting another source. For a DTMF menu, receive the usual Session DTMF event and call playback/stop before preparing the selected source when you need the current audio to stop first.

A 202 response confirms durable asynchronous admission. It does not confirm that previous playback has stopped or that new playback has started.

After admission:

• For files, the platform prepares source 0 first and can begin caller playback without waiting for the complete playlist. It then keeps up to five following sources ready ahead of the source being consumed, preparing another source as playback advances.
• For live streams, source fetching and decoding begin after the 202; fetch, format, or decode failures emit playback.failed with reason media_unavailable.
• The platform emits playback.started when it estimates that playback began.
• Any platform, source, or preparation failure after admission emits one operation-level playback.failed. Because later sources are prepared asynchronously, this event can occur before or after playback.started.
• An explicit stop or replacement before playback starts emits playback.stopped, which may precede any playback.started.

Triggered webhooks: playback.started, playback.stopped, and playback.failed.

See Playback lifecycle events for complete payload schemas and examples.

Match the operation_uuid in every playback webhook to the value returned by the 202 response.

{
  "type": "files",
  "urls": [
    "https://media.example.com/greeting.mp3",
    "https://media.example.com/menu.wav"
  ]
}

{
  "type": "stream",
  "url": "https://media.example.com/live"
}

{
  "type": "push",
  "media_format": {
    "encoding": "pcm_s16le",
    "sample_rate": 24000
  }
}

POST {ingest.url}
Authorization: Bearer <app_uuid>:<api_key>
Content-Type: application/octet-stream
<raw audio bytes>

{
  "type": "silence"
}

An accepted request returns 202 Accepted with operation_uuid and status: in_progress. New playback replaces active playback automatically. See Playback lifecycle events for completion and failure webhooks.