What the ra_call_control API does

The ra_call_control function is part of the VICIdial Agent API (agc/api.php). It lets an external application hang up or transfer a call that a Remote agent is currently on — and optionally record a Disposition and call length for that call. Remote agents work over forwarded phone lines and have no full agent screen, so this API fills the gap that the normal web interface would otherwise cover.

Why you would script this

A standard VICIdial Agent working at a browser can click to transfer or hang up directly in the agent screen. A remote agent receives calls on a plain phone line and has limited in-browser controls, or no browser access at all in some setups. ra_call_control gives your CRM, mobile app, or custom dashboard the ability to act on that call without the agent needing to navigate a web form. You send one HTTP GET or POST to api.php with the right parameters and VICIdial handles the rest.

This matters most in field-agent or work-from-home setups where agents use a personal cell phone as their Extension rather than a desk phone with a full softphone client. Your application knows the state of each call and can issue commands against the ra_call_control endpoint based on whatever logic your business requires — for example, auto-hanging up after a timeout, or routing the call based on the customer's CRM record.

Authentication follows the standard agent API pattern: a source parameter, a user parameter (a VICIdial user with level 4 or higher and Agent API Access enabled), and a pass parameter. Those three fields must be valid before VICIdial will process any ra_call_control request.

The required parameters

• value — the call ID of the active call. VICIdial delivers this in the CallerIDname field or a SIP header when the call is sent to the remote agent. An example looks like Y0315201639000402027. This is the unique handle that ties your API request to the right call.
• agent_user — the VICIdial username of the remote agent handling the call. This is alphanumeric and must match an agent that is currently logged in.
• stage — what action to take. Three choices: HANGUP, EXTENSIONTRANSFER, or INGROUPTRANSFER. Each stage may require one additional parameter depending on the action.

How the call flows

flowchart TD
  A["External app builds API request"] --> B["POST to agc/api.php"]
  B --> C{"Auth valid?"}
  C -->|No| D["ERROR: no user found"]
  C -->|Yes| E{"agent_user logged in?"}
  E -->|No| F["ERROR: user not logged in"]
  E -->|Yes| G{"Active call found for value?"}
  G -->|No| H["ERROR: no active call found"]
  G -->|Yes| I["Execute stage action"]
  I --> J["SUCCESS response returned"]

The optional status parameter

The optional status parameter lets you set a disposition code (up to 6 characters) at the same time the action runs. If you leave it out, VICIdial defaults to RAXFER. This means your external system can log a call outcome — for example, passing a code like SALE or CBCK — in the same request that ends or routes the call. Combining the action and the disposition into one request reduces round trips and keeps the call record accurate even if your app loses connectivity immediately after the transfer.

Typical error responses

When something is wrong, VICIdial returns a descriptive ERROR string rather than a generic failure code. You will see responses like ERROR: no user found, ERROR: user not logged in, ERROR: no active call found, or ERROR: stage is not valid. These make it straightforward to trace exactly where a request broke down. Build your integration to check the response string and surface these errors in your application logs.

There is also a general ERROR: ra_call_control not valid that fires when the overall request fails validation — usually because a required parameter is missing entirely. A success response includes the agent user and call ID so you can confirm the right call was acted on. Log both the request parameters and the response string so you can reconstruct what happened to any call later.

For a walkthrough of the three stage options and what each one requires, see the three stages of ra_call_control explained. The broader context of how remote agents work in VICIdial is covered in the remote agents guide. If you want a VICIdial system ready to test this API without building a server from scratch, our managed VICIdial plans give you a running dialer in under 40 seconds.