Pulling a fronter off a 3-way with force_fronter_leave_3way

In a typical Three-way call transfer workflow, a Fronter dials and qualifies the prospect, then bridges a Closer into the call to handle the pitch or close. At some point the fronter needs to drop off so the closer and the prospect can speak privately. That handoff usually depends on the fronter clicking a button — but with the force_fronter_leave_3way function, your system can trigger that exit automatically.

The function works from the closer's side. You call it for the Agent who is the closer — identified by agent_user — and VICIdial finds the other agent on the same lead and sends them the leave-3way command. It looks for the oldest other user currently on a call with the same lead_id that the named agent is talking to. This means you do not need to know the fronter's username in advance — the API matches on the shared call instead.

How the command finds and removes the fronter

sequenceDiagram
  participant App as Closer App
  participant API as agc/api.php
  participant Closer as Closer Session
  participant Fronter as Fronter Session
  App->>API: force_fronter_leave_3way agent_user=closer value=LOCAL_ONLY
  API->>Closer: get lead_id of current call
  API->>Fronter: find oldest other agent on same lead_id
  Fronter-->>API: fronter agent found
  API->>Fronter: send leave_3way command
  Fronter-->>API: command delivered
  API-->>App: SUCCESS force_fronter_leave_3way SENT - fronter_id

The function does not execute the leave for the named agent_user — it targets the other agent on the call. If no fronter is found, the API returns ERROR: no fronter found and nothing happens. This design means you always issue the command from the perspective of whoever should stay on the line, which is usually the closer.

Parameters and the three scope values

The required value parameter controls where VICIdial looks for the fronter:

LOCAL_ONLY searches only the current cluster. Use this for standard single-server setups, which covers most deployments.

LOCAL_AND_CCC checks the local cluster first, then sends the command to a remote CCC (call center cluster) if the fronter is not found locally. Reach for this when fronters and closers may live on either side of a linked pair of systems.

CCC_REMOTE targets a remote cluster only, for situations where the closer's cluster and the fronter's cluster are different systems. When using CCC_REMOTE, you may also pass the optional lead_id parameter to help identify the correct call on the remote side. The lead_id is only meant for use with CCC_REMOTE commands; the two local modes resolve the fronter without it.

# Local cluster only
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=force_fronter_leave_3way&value=LOCAL_ONLY"

# Local cluster plus remote CCC fallback
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=force_fronter_leave_3way&value=LOCAL_AND_CCC"

Successful responses include the fronter's user ID for local finds, or the CCC name for remote:

SUCCESS: force_fronter_leave_3way SENT - 6667
SUCCESS: force_fronter_leave_3way command sent over CCC - test_ccc

When to use this and what to watch for

The common automation pattern is: your CRM detects that the closer has accepted the warm transfer, waits a defined number of seconds, then calls force_fronter_leave_3way to drop the fronter without requiring them to remember to click Leave. This keeps the Agent session data clean and removes a manual step that fronters sometimes forget, especially on high-volume shifts where every saved second compounds.

There is a sibling function, force_fronter_audio_stop, that uses the same three scope values to stop any audio playing in the fronter's session instead of removing them from the call. The two are often used together: stop the fronter's hold or pitch audio, then pull them off the bridge. Note that force_fronter_audio_stop can return a permission error if the API user lacks rights to it, so test access before relying on it in production.

This function works alongside the broader Agent API toolkit. Other functions in that set — including switch_lead and pause_code — handle different phases of the Non-agent API and agent-side call lifecycle.

For a broader look at how all these functions fit together, see how to call the Non-Agent API and the VICIdial API and AGI overview. To run a VICIdial server where both APIs are configured and ready from the start, see VICIfast plans — each box provisions in under 40 seconds.