Driving transfers and conferences with transfer_conference

The transfer-conf frame on the VICIdial agent screen is where most call routing happens, and transfer_conference is the Agent API function that drives that frame from outside the screen. One endpoint covers hangups, blind transfers, voicemail drops, routing to another agent, and full Three-way call conferences. For how it sits among the other call-control endpoints, see the VICIdial API overview.

When you'd use it

Reach for it whenever a custom button needs to move or join a call. A Cold transfer to a fixed number is a BLIND_TRANSFER; a Warm transfer where the agent talks to a colleague first is a LOCAL_CLOSER or a consultative DIAL_WITH_CUSTOMER. It also handles dropping a voicemail, leaving two parties in conference, and parking the customer while you dial out. Because it mirrors the on-screen frame, anything an agent can do with those buttons you can script here.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Third as Third Party
  App->>API: transfer_conference (agent_user, value, opts)
  API->>V: validate value and options
  V->>Third: dial number or in-group
  V->>V: bridge or release the leg
  V-->>API: SUCCESS function set
  API-->>App: result line

You pick the action in value and add the options that action needs. For routing to a colleague the call lands in an Ingroup; for a 3-way the new leg is bridged onto the existing call so customer and third party hear each other. Which actions a user can fire depends on their level, as covered in VICIdial API user-level permissions.

Parameters

• value - REQUIRED. HANGUP_XFER, HANGUP_BOTH, BLIND_TRANSFER, LEAVE_VM, LOCAL_CLOSER, DIAL_WITH_CUSTOMER, PARK_CUSTOMER_DIAL, or LEAVE_3WAY_CALL.
• phone_number - OPTIONAL/REQUIRED, needed for any transfer or dial value.
• ingroup_choices - OPTIONAL/REQUIRED, needed for LOCAL_CLOSER and consultative transfers; a single active in-group, or DEFAULTINGROUP for the originating campaign's in-group.
• consultative - OPTIONAL, YES or NO, only with DIAL_WITH_CUSTOMER or PARK_CUSTOMER_DIAL.
• dial_override - OPTIONAL, YES or NO; dials exactly the number with no campaign phone code or prefix.
• group_alias and cid_choice - OPTIONAL, set the caller ID for DIAL_WITH_CUSTOMER or PARK_CUSTOMER_DIAL; cid_choice takes CAMPAIGN, AGENT_PHONE, CUSTOMER, or CUSTOM_CID.
• multi_dial_phones, md_check, tw_check - OPTIONAL, for Agent 3-way Press-1 calls and active-call checks.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=transfer_conference&value=LOCAL_CLOSER&ingroup_choices=SALESLINE

A blind transfer would be value=BLIND_TRANSFER&phone_number=8500, and a consultative 3-way would be value=DIAL_WITH_CUSTOMER&ingroup_choices=TEST_IN3&consultative=YES. A clean run returns a line like SUCCESS: transfer_conference function set - LOCAL_CLOSER|SALESLINE||YES|6666|M2141842580000000044|. Watch for ERROR: agent_user does not have a live call - 6666, ERROR: ingroup is not valid - XYZINGROUP, and ERROR: value is not valid - XYZFUNCTION|6666.

The gotcha

The required-but-optional fields catch everyone. phone_number is listed as optional in general but is mandatory for any dial or transfer value, and ingroup_choices is mandatory for LOCAL_CLOSER and consultative transfers, so leaving them off returns an ingroup or value error rather than doing nothing quietly. If you're firing repeated 3-way calls, set tw_check=YES so VICIdial refuses to start a new one while a previous 3-way is still live, which is how you avoid stacking ghost legs onto an agent. For controlling a remote agent's call, which is a separate and narrower path, see ra_call_control for remote agents.

Building custom transfer and conference controls is far easier on a dialer you own outright. VICIfast gives you a single-tenant VICIdial server with the agent API exposed, ready in under 40 seconds. See the plans to get a box to build on.