How to hang up a remote-agent call with ra_call_control

When a Remote agent is on an active call and your external application needs to end it programmatically, you use the ra_call_control function with stage=HANGUP. This is the simplest of the three stages because it needs only the three core parameters — no phone number, no in-group name. Send the request, get a success response, and VICIdial disconnects the call on both sides.

Parameters you need

• source — identifies your API client. Any string works; it shows up in API logs.
• user and pass — a VICIdial user with level 4 or higher and Agent API Access turned on. This is not the remote Agent user; it is the API-authorized account your app authenticates with.
• agent_user — the VICIdial username of the remote agent who has the call. Must be currently logged in and on an active call.
• function=ra_call_control — tells api.php which function to run.
• stage=HANGUP — the action to take.
• value — the call ID of the active call, delivered to your app via the CallerIDname field or a SIP header when the call was sent to the remote agent. An example: Y0315201639000402027. This changes with every call.
• status (optional) — a Disposition code up to 6 characters to log against the call. If omitted, VICIdial records RAXFER. Setting this in the same request saves a follow-up API call.

How the request flows

sequenceDiagram
  participant App as External App
  participant API as agc/api.php
  participant VD as VICIdial
  App->>API: GET api.php?function=ra_call_control&stage=HANGUP&value=Y...&agent_user=1028
  API->>API: Validate user and pass
  API->>VD: Look up agent_user session
  VD-->>API: Agent logged in, active call found
  API->>VD: Execute HANGUP on call
  VD-->>API: Call disconnected
  API-->>App: SUCCESS: ra_call_control hungup - 1028|Y...|HANGUP

Success and error responses

A clean hangup returns: SUCCESS: ra_call_control hungup - followed by the Agent API user, the call ID, and HANGUP. The success string confirms which call was terminated and which agent was on it, so you can match it back to your application's call record. If something goes wrong, VICIdial returns one of these specific errors:

• ERROR: no user found — the user/pass combination does not match a valid API user with the right access level.
• ERROR: user not logged in — agent_user is a valid VICIdial user but is not currently in an active session. They may have timed out or not logged in yet.
• ERROR: no active call found — the value you passed does not match any call the agent is currently on. The call may have already ended or the call ID may be from an earlier call.
• ERROR: ra_call_control not valid — the overall request did not pass validation. Check that all three required parameters are present and correctly spelled.

These error strings are designed to tell you exactly which check failed. Build your integration to log the full response string, not just whether the request returned HTTP 200. VICIdial returns 200 even for error responses — the success or failure is in the body text.

If you need to transfer rather than hang up, the EXTENSIONTRANSFER and INGROUPTRANSFER stages are covered in how to transfer a remote-agent call to a phone number. Background on the agent API and how remote agents fit into VICIdial is in the remote agents guide. To skip building a server and get a VICIdial system running in under 40 seconds, see our managed VICIdial plans.