Controlling a remote agent's call with ra_call_control

A Remote agent in VICIdial is an agent who takes calls on a plain phone number rather than through the browser agent screen, so the normal on-screen transfer and hangup buttons aren't available to them. ra_call_control is the Agent API function that fills that gap: it lets an outside system hang up or transfer the call a remote agent is on, and optionally log a disposition and call length. For where it sits among the other endpoints, see the VICIdial API overview.

When you'd use it

Use it when remote agents work calls off a softphone or a hardphone and you've built your own control panel for them. Because they have no agent screen, your panel becomes their hangup and transfer buttons, and ra_call_control is the wire behind those buttons. It is deliberately narrow: it supports only three stages, HANGUP, EXTENSIONTRANSFER, and INGROUPTRANSFER. There is no parking, no conference, no DTMF here. If you need richer call handling you're looking at a normal on-screen agent and transfer_conference instead.

How the call works

sequenceDiagram
  participant Panel
  participant API as api.php
  participant V as VICIdial
  participant Caller
  Panel->>API: ra_call_control (value, agent_user, stage)
  API->>V: find call by ID
  V->>V: apply HANGUP or transfer
  V->>Caller: route or drop the line
  V-->>API: SUCCESS transferred/hungup
  API-->>Panel: result line

The function locates the active call by its ID, confirms the remote agent owns it, then applies the chosen stage. For an Ingroup transfer it drops the call into a Call queue in-group; for an extension transfer it dials a full number through the default context. The reply format follows the usual pattern explained in reading VICIdial API responses.

Parameters

• value — REQUIRED, the call ID as seen in the CallerIDname field or a special SIP header, e.g. Y0315201639000402027.
• agent_user — REQUIRED, the remote agent's user login.
• stage — REQUIRED, one of HANGUP, EXTENSIONTRANSFER, INGROUPTRANSFER.
• ingroup_choices — OPTIONAL, required only for INGROUPTRANSFER; a single active in-group, or DEFAULTINGROUP to use the in-group or campaign that originated the call.
• phone_number — OPTIONAL, required only for EXTENSIONTRANSFER; a full number dialable through the default context.
• status — OPTIONAL, the disposition status for the call, max 6 characters; defaults to RAXFER if unset.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1028&function=ra_call_control&stage=INGROUPTRANSFER&ingroup_choices=DEFAULTINGROUP&value=Y0316001655000402028

A successful transfer returns SUCCESS: ra_call_control transferred - 6666|Y0315201639000402027|SALESLINE, and a hangup returns SUCCESS: ra_call_control hungup - 6666|Y0315201639000402027|HANGUP. The common failures are ERROR: no active call found - <id>, ERROR: ingroup is not valid - TESTINGROUP, ERROR: phone_number is not valid - 9, and ERROR: stage is not valid - XYZ.

The gotcha

Getting the call ID right is the whole game. It comes from the CallerIDname field or a special SIP header, not from a lead_id or a uniqueid, so if you feed it the wrong identifier you'll get ERROR: no active call found even though the agent is plainly on a call. Capture that ID when the call lands at the remote agent and carry it through your panel. For the on-screen counterpart that handles the richer transfers this function can't, see driving transfers with transfer_conference.

Remote-agent setups want a dialer you fully own so you can wire your own control panel against the API. VICIfast hands you a single-tenant VICIdial server, HTTPS included, ready in under 40 seconds. Check the plans and start building.