How to transfer a remote-agent call to a phone number via the API

The EXTENSIONTRANSFER stage of ra_call_control performs a blind transfer of a Remote agent call to a specific phone number. Your external app passes a phone_number parameter containing the full number to dial, and VICIdial immediately bridges the call to that destination. The remote agent is released and the caller moves to the new number without any hold or consultation period.

What EXTENSIONTRANSFER does

This is a Cold transfer: VICIdial bridges the caller to the destination number and drops the remote agent out of the call. There is no warm handoff or consultation step. It is appropriate when you want to move a call to a specific Extension, a direct-dial number, a voicemail box, or an outside line without putting the caller into a queue. The number is dialed through the server's default context, so it follows the same routing rules as any other outbound dial from that server.

A common use for this stage is routing a call to a manager's direct number, sending a caller to a specialized departmental line, or forwarding to an off-platform system that your VICIdial in-group does not cover. Because the number is free-form and routed through the dialplan, you have flexibility over the destination without needing to configure a VICIdial Ingroup for every possible transfer target.

Parameters required

• source, user, pass — standard API auth. The user must have level 4 or higher with Agent API Access.
• function=ra_call_control — selects the ra_call_control function in api.php.
• stage=EXTENSIONTRANSFER — tells VICIdial this is a number transfer.
• value — the call ID received when the call was delivered to the remote agent. For example: Y0315201639000402027.
• agent_user — the VICIdial username of the remote agent currently on the call.
• phone_number — the full number to dial, including any prefix your system needs to reach the destination. If you dial an outside line with a leading 9, include that 9 here. A partial or invalid number returns ERROR: phone_number is not valid.
• status (optional) — a Disposition code up to 6 characters. Defaults to RAXFER if omitted.

Request flow

sequenceDiagram
  participant App as External App
  participant API as agc/api.php
  participant VD as VICIdial
  participant Dest as Destination Number
  App->>API: GET api.php?stage=EXTENSIONTRANSFER&phone_number=18005551234&agent_user=1028&value=Y...
  API->>API: Validate auth and parameters
  API->>VD: Find agent session and active call
  VD-->>API: Agent logged in, call confirmed
  API->>VD: Blind-transfer call to phone_number
  VD->>Dest: Dial 18005551234 via default context
  VD-->>API: Transfer bridged
  API-->>App: SUCCESS: ra_call_control transferred - 1028|Y...|18005551234

Common errors and what they mean

ERROR: phone_number is not valid fires when the phone_number parameter is missing, empty, or fails VICIdial's format check — for example, passing a single digit like 9 as the entire number. Pass the full dialable number, not a short code or extension alias. The other error messages (no user found, user not logged in, no active call found) follow the same pattern as the HANGUP stage and mean the same things: the auth failed, the agent is not in session, or the call ID does not match an active call.

A successful response looks like SUCCESS: ra_call_control transferred - followed by the agent user, call ID, and the destination number. Store this response so you can confirm which call was transferred where. The Campaign that originated the call will record the transfer with the status code you supplied — or RAXFER if you left it out.

If you need to send the call into a queue rather than to a specific number, use INGROUPTRANSFER instead — that is covered in how to transfer a remote-agent call into an in-group. For the full context on how remote agents work, see the remote agents guide. Our managed VICIdial plans give you a configured server in under 40 seconds so you can test this without a manual setup.