Playing audio to a caller with the audio_playback function

The audio_playback function plays a sound file into a live Agent session and gives you basic transport control over it — stop, pause, resume, restart. It's part of the VICIdial Agent API, and it's the call you reach for when you want a recorded message played to the caller on cue rather than read out by the agent. For the wider context, see the VICIdial API overview.

When you'd use it

Think of the recorded snippets agents shouldn't have to recite by hand: a legally worded disclosure, a pricing readout, a long terms-and-conditions clip. You can trigger those from a button in your own UI and let the box play the file cleanly every time. It overlaps in spirit with a Voicemail drop, but here you're playing into a live conversation, not leaving a message — closer to a mini IVR (interactive voice response) step the agent fires on demand.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Caller
  App->>API: audio_playback (value=file, stage=PLAY)
  API->>V: load file from audio store
  V->>Caller: audio plays into the call
  V-->>App: SUCCESS audio_playback function sent
  App->>API: audio_playback (stage=STOP)
  API->>V: kill playback
  V-->>App: SUCCESS

Unlike most agent-api calls, the action verb lives in the stage parameter, not value. The value parameter carries the audio file name, and it's only required when you're starting playback.

Parameters

• stage — REQUIRED. PLAY starts a new file, STOP kills playback, PAUSE pauses, RESUME resumes after a pause, RESTART restarts from the beginning.
• value — REQUIRED for a stage of PLAY. The name of the audio file in the audio store to play, with NO file extension.
• dial_override — OPTIONAL, Y or N, default N. Lets you PLAY a file without first issuing a STOP to whatever is currently playing.

One note worth keeping in mind: PAUSE, RESUME, and RESTART need Asterisk 1.8 or higher. On older Asterisk you can fake RESTART by issuing a PLAY with dial_override set on.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=audio_playback&value=ss-noservice&stage=PLAY

A clean start returns SUCCESS: audio_playback function sent - ss-noservice|PLAY|6666. If something is already playing you get ERROR: audio_playback error - audio already playing in agent session, and a PAUSE with nothing running returns ERROR: audio_playback error - no audio playing in agent session. When dial_override lets a new file override the old one, you'll see NOTICE: audio_playback previous playback stopped - PLAY|Y|6666.

Gotchas to watch

The most common mistake is putting the file extension in value — the audio store wants the bare name, so use ss-noservice, not ss-noservice.wav. The second is forgetting the stage-versus-value split: a PLAY needs both stage=PLAY and a value, while STOP, PAUSE, RESUME, and RESTART take only the stage. And without dial_override, firing a second PLAY while audio is running gives you the "already playing" error instead of switching files, which surprises people building a quick "play this clip now" button. This isn't Music on hold — it plays straight into the live call. For finding and managing the resulting recordings, the recording lookup function is the companion call.

Playing compliant audio on cue is the kind of thing a managed VICIdial box makes painless, with the agent API ready from day one. See our plans.