How to start and stop a recording from your own app

You do not have to rely on campaign-level recording settings or agent button presses to capture calls. VICIdial's Agent API lets your CRM, ticketing system, or custom web app fire a recording START when the right moment arrives—and a STOP when it is over.

What you need before writing a single line of code

• An API user account in VICIdial with permission to use the Agent API.
• The agent login ID (agent_user) of the session you want to control.
• Network access from your app's server to VICIdial's web server on port 80 or 443.
• The agent must be logged in and the browser screen active when the signal arrives—otherwise the signal lands but nothing starts.

Step-by-step: triggering a recording start

1. Detect the moment in your app when recording should begin—payment data entry, a compliance script, a supervisor-required segment.
2. Issue an HTTP GET to: /agc/api.php?source=myapp&user=APIUSER&pass=APIPASS&agent_user=AGENTID&function=recording&value=START
3. Parse the response. A line beginning with SUCCESS confirms the signal was received. A line beginning with ERROR tells you what went wrong.
4. Wait a second, then call STATUS to confirm the recording_id and filename exist. Store the filename in your app for later retrieval.
5. When the segment ends, call STOP. Confirm with another STATUS call—if it returns NOTICE: not recording, the file is closed and being written to disk.

App-controlled recording flow

flowchart TD
  A[App detects trigger event] --> B[POST START to api.php]
  B --> C{Response starts with SUCCESS?}
  C -->|No| D[Log error and alert supervisor]
  C -->|Yes| E[Call STATUS after 1 second]
  E --> F{recording_id returned?}
  F -->|No| D
  F -->|Yes| G[Store filename in app]
  G --> H[Segment ends - call STOP]
  H --> I[Call STATUS to confirm closed]
  I --> J[File available on disk]

Multiple recordings on the same session

The recording function allows multiple concurrent recordings on one agent Session ID. Each START call creates a new recording file. A single STOP, however, halts all of them at once. If you need segment-level granularity—for example, recording only the payment section—use the stage parameter (covered in a separate post) to tag each START with a suffix so you can identify segments after the fact.

Handling edge cases cleanly

**Gotcha:** If the agent logs out between your START and your STOP, you will get ERROR: agent_user is not logged in on the STOP call. The recording file may still exist on disk in a partial state—Asterisk's MixMonitor usually closes the file on hangup anyway, but you should verify by checking the Call recording log table in the database rather than assuming the file is complete.

Also watch the agent_status field in every response. If it reads READY or INCALL instead of PAUSED, the agent is actively on a call—that is the expected state for a recording to matter. A PAUSED status with a recording active usually means the agent started a recording, then went to pause mode; the file is still accumulating audio on the Asterisk server.

For a full breakdown of how call recording works at the campaign level before you layer API control on top, read VICIdial call recording explained. To understand what the recording Agent API function's parameters look like in detail, see the recording Agent API function reference.

Want a managed environment where the Agent API is pre-configured and ready for integration? See VICIfast pricing.