The transfer_conference API: scripting transfers and 3-way calls

Most of the transfer buttons an agent clicks on the VICIdial screen have a programmatic twin. The transfer_conference function in the Agent API sends the same commands the transfer-conf frame would, except the trigger comes from an outside program instead of a mouse click. If you run a CRM, a wallboard, or a custom toolbar, this is how you wire a transfer into it without rebuilding the agent screen.

What the call does

transfer_conference is part of the agent-side API (application programming interface), so the request always names the agent whose session you are acting on. You pass a source program name, a user and password with API access, the agent_user whose call you want to move, the function name, and a value that says which command to run. The value is the part that decides everything: HANGUP_XFER drops only the third party, HANGUP_BOTH ends the customer and the third party, BLIND_TRANSFER pushes the customer to a number, LOCAL_CLOSER sends the call to another agent through an Ingroup, and DIAL_WITH_CUSTOMER opens a 3-way with the customer still on the line.

Because the function only acts on a live call, the agent must be logged in and actually connected to a customer. If the agent_user has no live call, the request comes back with an error rather than silently doing nothing, which makes it safe to fire from automation that might race ahead of the agent.

The decision flow

flowchart TD
  A[External program] --> B[Call transfer_conference]
  B --> C{Which value}
  C -->|BLIND_TRANSFER| D[Customer sent to number]
  C -->|LOCAL_CLOSER| E[Call routed to closer ingroup]
  C -->|DIAL_WITH_CUSTOMER| F[Three way call opens]
  C -->|HANGUP_XFER| G[Third party dropped]
  D --> H[Agent freed]
  E --> H
  F --> I[Agent stays on line]

Two values cover the warm path. DIAL_WITH_CUSTOMER builds a Three-way call so the agent can introduce the customer to whoever answers, and LEAVE_3WAY_CALL lets the agent step out afterward, leaving the customer and the third party talking while the agent lands on the Disposition screen. PARK_CUSTOMER_DIAL is the private-briefing version: the customer goes to park while the new call is placed, so they do not overhear the introduction.

Picking a target

Any value that dials needs a target. Transfers to a number take a phone_number field. Sending the call to a Closer with LOCAL_CLOSER takes an ingroup_choices field naming a single active in-group, and the reserved word DEFAULTINGROUP routes to whatever in-group or campaign the call came from. If you want the call to land on one specific agent rather than a queue, you point ingroup_choices at AGENTDIRECT and add that agent in the phone_number field. Consultative transfers between two agents add a consultative flag, but only on the DIAL_WITH_CUSTOMER and PARK_CUSTOMER_DIAL values.

If you are deciding between a 3-way and a straight handoff before you script anything, the trade-offs are laid out in warm versus cold transfer in VICIdial. The API gives you both, so the choice stays a workflow question rather than a technical one.

transfer_conference is one tool in a larger handoff system, and it fits the same fronter-to-closer chain described in our transfers and closers guide. Scripting it means your CRM and your dialer agree on what a transfer is, instead of each tracking its own version.

If you want a dialer where the transfer API is already enabled and documented rather than something you have to fight for, look at our pricing and get an environment that is ready to script from day one.