The recording Agent API function: START, STOP, STATUS

VICIdial's Agent API exposes a function called recording that lets any external system signal an agent session to start or stop capturing audio—without the agent touching a button. It also provides a STATUS query so you can confirm what is actually recording right now.

What the function does

The function targets a specific agent session identified by agent_user and sends a signal to that agent's browser screen. The screen then acts on the signal—starting or stopping Call recording just as if the agent had clicked the record button themselves.

Three values are available for the value parameter:

• START — sends a start-recording signal. Multiple recordings can run simultaneously on the same agent session.
• STOP — sends a stop-recording signal that halts all active recordings on the agent screen at once.
• STATUS — returns a pipe-delimited string: user|recording_id|filename|server|start_time|agent_server|session|agent_status. If no recording is active you get a NOTICE: not recording response instead.

Building the API call

The endpoint is /agc/api.php. Required query parameters are source, user (the API user), pass, agent_user (the agent whose session you are targeting), function=recording, and value. A minimal START call looks like this:

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

A successful response confirms the action: SUCCESS: recording function sent - 6666|START||||192.168.1.5|8600051|PAUSED. The agent_status field at the end shows the current agent state—PAUSED here means the agent is between calls.

Signal flow from API call to active recording

sequenceDiagram
  participant App as External App
  participant API as api.php
  participant Screen as Agent Screen
  participant Asterisk as Asterisk
  App->>API: function=recording value=START
  API->>Screen: start recording signal
  Screen->>Asterisk: MixMonitor command
  Asterisk-->>Screen: recording_id and filename
  Screen-->>API: SUCCESS response
  API-->>App: SUCCESS recording function sent

Common error responses

• ERROR: no user found — the API user credential is wrong or missing.
• ERROR: agent_user is not logged in — the target agent has no active session; the signal has nowhere to go.
• ERROR: stop recording error — VICIdial tried to stop a recording but the underlying stop command failed, often because the recording had already ended.

The STATUS value is your best tool for diagnosing these situations. Poll it before issuing a STOP to confirm a recording is actually in progress.

START sends a signal, not a direct command

**Heads up:** The API does not speak directly to Asterisk. It signals the agent's browser screen, which then fires the Asterisk MixMonitor command. If the agent screen is not loaded or the browser has timed out, the signal is received by the server but has no active listener to act on it. Always pair START with a follow-up STATUS call to verify the Recording format (WAV/MP3) and filename were created.

For a broader look at how recording fits into your call center setup, see VICIdial call recording explained. If you want to see how the stage parameter tags your recordings mid-call, check out how to tag a recording with the stage parameter.

Need a fully managed VICIdial host where the API is already enabled? See VICIfast pricing.