VoiceplayAudio

Play audio

Name: Hey Quad
Availability: InStock

Plays an audio file to the caller — pick a built-in clip (hold music, ringback) or paste any public MP3/WAV URL. Loops until the next step unless you set…

type: playAudio status: stable sinceVersion: 0.1.0 seeAlso: [say, playMusic, enqueue, wait] keywords: [audio, file, mp3, wav, hold music, ringback, loop, whisper, announcement]

What it does

Plays an audio file to the caller — either a built-in clip (the bundled hold-music / ringback presets) or any public MP3/WAV URL. It loops a fixed number of times, or Forever (until the next step takes over). By default only the caller hears it; Heard by can whisper it to the bridged agent or play it on Both legs in parallel.

This is the plain "play this file" step. For a spoken prompt or text-to-speech, use Play prompt or audio (say). For hold music with a start offset, a play-time window, resume, or press-a-key-to-skip, use Play music (playMusic).

When to use it

Loop hold music or ringback while agents ring or a caller waits.
Play a static announcement — an outage notice, a recorded greeting, a legal disclosure — once.
Whisper a short audio cue to the answering agent.

Configuration

Plays an audio file to the caller — pick a built-in clip (hold music, ringback) or paste any public MP3/WAV URL. Loops until the next step unless you set a finite count. Set "Heard by" to "Agent only" to whisper it to the bridged agent, or "Both" to play it on every leg in parallel. For a one-off spoken prompt use "Play prompt or audio"; for hold music with start offset, play-time, resume, or press-a-key-to-skip, use "Play music".

Field	Label	Type	Required	Default	Notes
`audioUrl`	Audio	`audioUrl`	Required	`""`	Pick a built-in clip or paste any public MP3/WAV URL.
`loop`	How many times	`select`	Optional	`infinity`	Options: `infinity`, `1`, `3`, `5`, `10`.
`target`	Heard by	`select`	Optional	`caller`	Options: `caller`, `agent`, `both`. Agent-only whisper requires an active bridged agent leg. "Both" plays in parallel on the caller leg and every active bridged leg; the call advances when the caller leg finishes. Falls back to the caller leg only if no bridge is active.

Outgoing events: call.playback.ended, call.hangup

Examples

Loop hold music while ringing

{
  "id": "hold",
  "type": "playAudio",
  "config": { "audioUrl": "opusringback", "loop": "infinity" },
  "on": { "call.playback.ended": "voicemail", "call.hangup": "end" }
}

Play a one-off announcement

{
  "id": "notice",
  "type": "playAudio",
  "config": { "audioUrl": "https://cdn.example.com/outage.mp3", "loop": "1" },
  "on": { "call.playback.ended": "menu", "call.hangup": "end" }
}

Gotchas

Forever loop holds the verb queue. A Forever clip keeps playing until the call bridges (an agent answers), hangs up, or another verb cancels it. That's the point for hold music, but don't put a Forever clip in front of a step you expect to reach on its own.
Heard by: agent / both needs an active bridge. With no agent leg in scope it falls back to the caller leg.
Audio URLs must be publicly reachable. The media server fetches the file server-side; private or expired-signed URLs fail and the flow stalls on call.playback.ended.

All nodes