The three stages of ra_call_control explained

Every ra_call_control request must include a stage parameter. Stage tells VICIdial what to do with the call the Remote agent is currently handling. There are exactly three valid values: HANGUP, EXTENSIONTRANSFER, and INGROUPTRANSFER. Choosing the wrong one, or omitting a required companion parameter, returns an error and leaves the call untouched. Understanding what each stage does — and what it needs — is the key to building a reliable integration.

HANGUP

HANGUP ends the call. No additional parameters are required beyond the standard trio of value (call ID), agent_user, and stage. VICIdial disconnects the active call and returns SUCCESS: ra_call_control hungup followed by the agent user and call ID. You can optionally include a status parameter to set a Disposition at the same time — if you leave it out, VICIdial defaults to RAXFER. This stage is appropriate when your application decides the call should be terminated entirely rather than passed somewhere else. Common use cases include post-timeout cleanup, auto-hangup after a survey, or letting a supervisor-facing dashboard end a call on behalf of an agent.

EXTENSIONTRANSFER

EXTENSIONTRANSFER moves the call to a specific phone number. This stage requires a phone_number parameter that contains the full number as it needs to be dialed through the default Dialplan context on the server. If your PBX needs a prefix to reach an outside line, include it in phone_number. An invalid or incomplete number returns ERROR: phone_number is not valid. On success, VICIdial returns SUCCESS: ra_call_control transferred with the agent user, call ID, and destination. This is a blind transfer — the remote Agent is immediately dropped from the call when the bridge is made, with no consultation step before the caller reaches the destination.

INGROUPTRANSFER

INGROUPTRANSFER sends the call into a VICIdial Ingroup queue. This stage requires an ingroup_choices parameter set to a single active in-group name. The in-group must exist and be active on the server — passing a name that does not match returns ERROR: ingroup is not valid. There is one reserved value, DEFAULTINGROUP, which routes the call to whichever in-group or Campaign originally sent the call to the remote agent, without you needing to know the in-group name at call time. This is useful when calls can arrive from multiple different in-groups and you want them returned to their origin queue rather than a fixed destination.

Which extra parameter each stage needs

flowchart TD
  A["stage parameter"] --> B{"Which stage?"}
  B -->|HANGUP| C["No extra param needed"]
  C --> D["Call disconnected"]
  B -->|EXTENSIONTRANSFER| E["Requires phone_number"]
  E --> F{"phone_number valid?"}
  F -->|No| G["ERROR: phone_number is not valid"]
  F -->|Yes| H["Call transferred to number"]
  B -->|INGROUPTRANSFER| I["Requires ingroup_choices"]
  I --> J{"ingroup_choices valid?"}
  J -->|No| K["ERROR: ingroup is not valid"]
  J -->|Yes| L["Call enters in-group queue"]

The optional status parameter

All three stages accept the optional status parameter. It takes a disposition code of up to 6 characters and records it against the call at the same moment the action executes. This saves a separate API call and keeps your call records clean. If you omit it, the call records with RAXFER as the status. Use a code your VICIdial campaign recognizes so reporting picks it up correctly. Some teams use this to distinguish between different transfer reasons — for example, XSALE for a transfer to a sales closer versus XBILL for a billing escalation — even when the stage is the same.

For a closer look at how EXTENSIONTRANSFER works in practice, see how to transfer a remote-agent call to a phone number. The full picture of remote agents and how they receive calls is in the remote agents guide. If you need a VICIdial environment ready to test against, our managed VICIdial plans provision a dialer in under 40 seconds.