Starting and stopping recordings with the recording function

The recording function in the VICIdial Agent API lets an outside script start or stop a Call recording on a live agent's screen, or read back the status of whatever is recording right now. It acts on a logged-in Agent session, so the agent has to be logged in and on their phone for it to do anything. For the wider picture of how these calls are structured, see the VICIdial API overview.

When you'd use it

Reach for this when you want recording driven by something other than the agent clicking a button. A common case is on-demand recording — you start a recording from your own toolbar or wallboard at the moment a customer gives consent, then stop it when the sensitive part of the call is over. Another is a CRM that records every connected call automatically the instant a lead loads. Because you can fire START more than once, you can have several recordings running on the same call at the same time, each writing its own file.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: recording (agent_user, value=START)
  API->>V: send start signal to agent screen
  V->>Agent: recording begins
  V-->>App: SUCCESS recording function sent
  App->>API: recording (value=STOP)
  API->>V: stop all active recordings
  V-->>App: SUCCESS

Your script calls api.php with the agent's user and pass, names the agent in agent_user, and passes function=recording with a value. VICIdial pushes the signal to that agent's screen, the recording engine on the box acts on it, and the response comes straight back in the HTTP body.

Parameters

• value — REQUIRED. START sends a start signal (you can have several recordings going at once); STOP stops all active recordings on the agent screen; STATUS returns active recording and session info.
• stage — OPTIONAL. A label appended to the recording filename, limited to 14 characters (it truncates past that). Only works with the START value.

The STATUS value returns a pipe-delimited line in the order user, recording_id, filename, server, start_time, agent_server, Session ID, and agent_status — handy when you need to confirm a file actually started writing.

An example call

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

A clean start comes back as SUCCESS: recording function sent - 6666|START_MIDCALL||||192.168.1.5|8600051|PAUSED. A STATUS check that finds an active file returns NOTICE: recording active - 6666|121242|20120810-012008__6666_|192.168.1.5|2012-08-10 01:20:10|192.168.1.5|8600051|PAUSED, while a quiet line returns NOTICE: not recording. If the agent isn't logged in you get ERROR: agent_user is not logged in - 6666.

Gotchas to watch

STOP is blunt — it stops every active recording on that agent's screen, not just the one you started, so don't use it on a call where another process is also recording unless you mean to kill them all. The stage label only attaches on START, so trying to add it to a STOP does nothing. And the resulting file still follows your server's Recording format (WAV/MP3) and Recording delay settings — the API decides when, the box decides how. If you want stereo capture instead of a mono mix, the closely related recording lookup function helps you find files after the fact.

If you're building consent-driven recording into an agent workflow, a managed VICIdial box gives you the agent API ready to call out of the box. See what's included on our pricing page.