The stereo_recording API function explained: BEGIN, END, STATUS

VICIdial's Stereo recording feature separates the agent and customer onto distinct audio channels in a single file. The stereo_recording Agent API function lets an external system trigger and control that agent-controlled stereo recording—without waiting for the agent to act.

The three values

The value parameter is required and accepts exactly three options:

• BEGIN — starts an agent-controlled stereo recording. Unlike the standard recording function, you cannot run multiple stereo recordings at the same time on one agent session.
• END — stops all active agent-controlled stereo recordings on that session.
• STATUS — returns recording details only for agent-controlled stereo recordings: user|recording_id|filename|server|start_time|agent_server|session|agent_status. Campaign-level stereo recordings are not included in this response.

How stereo_recording differs from recording

The standard recording function uses START/STOP and can run multiple recordings simultaneously. The stereo_recording function uses BEGIN/END and is limited to one active agent-controlled recording at a time. Also, STATUS for stereo_recording only reflects agent-initiated recordings—it ignores any campaign-level stereo recording that may already be running in the background.

State transitions for agent-controlled stereo recording

stateDiagram-v2
  [*] --> Idle
  Idle --> Recording : BEGIN sent via API
  Recording --> Idle : END sent via API
  Recording --> Recording : STATUS query returns recording_id
  Idle --> Idle : STATUS query returns NOTICE not stereo_recording
  Recording --> Idle : Agent logs out or call ends

Example API calls and responses

A BEGIN call:

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=stereo_recording&value=BEGIN

Expected success response:

SUCCESS: stereo_recording function sent - 6666|BEGIN||||192.168.1.5|8600051|PAUSED

An END call:

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=stereo_recording&value=END

A STATUS call that finds an active recording returns a NOTICE line with the recording_id and filename, for example: NOTICE: stereo_recording active - 6666|121242|20120810-012008__6666_|192.168.1.5|2012-08-10 01:20:10|192.168.1.5|8600051|PAUSED

Error responses to watch for

• ERROR: stop stereo_recording error — the END signal was received but the underlying stop command failed, typically because no agent-controlled stereo recording was active.
• ERROR: agent_user is not logged in — the agent session does not exist; check the agent login before retrying.

**Heads up:** STATUS only surfaces agent-controlled stereo recordings, not campaign-level ones. If your campaign already runs stereo recording automatically, a STATUS call returning NOTICE: not stereo_recording does not mean no recording is happening—it just means no agent-controlled one is active. Check the Call recording log table for the full picture.

For the full context on how stereo recording works in VICIdial campaigns, read VICIdial call recording explained. You can also learn about the campaign-level setup in VICIdial stereo call recording explained.

Ready for a managed VICIdial platform with API access built in? See VICIfast pricing.