Stopping a fronter's audio with force_fronter_audio_stop

During a blended inbound or outbound campaign, it is common for a Fronter — the first agent who qualifies a caller — to play an audio file while a Closer takes over the call. If the closer needs to stop that audio mid-stream from their own screen, the force_fronter_audio_stop function is how you do it. It is part of the Non-agent API, the set of HTTP calls that let external systems and scripts drive agent screens without going through the live agent interface.

The function does not act on the agent named in agent_user. Instead, it looks for another user session that is currently on a call with the same lead_id as the named agent. In other words: the closer calls the API with their own user ID, and VICIdial hunts for the fronter who is still connected to that same lead, then sends a stop-audio command to that fronter's session.

How the function resolves the fronter

sequenceDiagram
  participant C as Closer App
  participant API as non_agent_api.php
  participant VLA as vicidial_live_agents
  participant F as Fronter Session
  C->>API: force_fronter_audio_stop agent_user=closer value=LOCAL_ONLY
  API->>VLA: find other session with same lead_id
  VLA-->>API: fronter user id found
  API->>F: stop audio_playback
  F-->>API: command acknowledged
  API-->>C: SUCCESS force_fronter_audio_stop SENT

The required parameter value controls where VICIdial searches. LOCAL_ONLY restricts the search to the local cluster. LOCAL_AND_CCC checks the local cluster first and then a remote Contact Center Cluster (CCC) if nothing is found locally. CCC_REMOTE is for situations where the closer is not on the same cluster as the fronter at all. When using CCC_REMOTE, you can also pass lead_id explicitly to remove any ambiguity about which lead ties the two sessions together.

Example calls and expected responses

# Stop fronter audio on the local cluster only
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=force_fronter_audio_stop&value=LOCAL_ONLY

# Stop fronter audio, checking local then CCC
http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=force_fronter_audio_stop&value=LOCAL_AND_CCC

A successful response looks like SUCCESS: force_fronter_audio_stop SENT - LOCAL_AND_CCC||6667|1234. If the fronter's session has no audio currently playing, you get an error back — force_fronter_audio_stop error - no audio playing in other agent session — rather than a silent success. That distinction matters if you are writing an automation that checks the response before taking a next step.

Things that can go wrong

Other error conditions to watch for: the named agent_user is not logged in, the agent is not currently on a call, or no fronter session was found with the same lead. In all these cases the API returns a specific error string so you can handle each one differently in your integration.

This function is purpose-built for Three-way call workflows where the fronter plays a recorded intro while the closer gets ready. Because the audio stop is triggered by the closer — not by the fronter — the handoff feels natural without requiring the fronter to manually interact with their screen. For Call recording considerations during that handoff, make sure your campaign's recording settings cover both legs.

To understand how this function fits alongside others in the agent API family, see the Non-Agent API vs Agent API comparison. For the full picture of every API and AGI function available in VICIdial, visit the VICIdial API and AGI overview. If you want a managed VICIdial host with API access ready out of the box, VICIfast plans include a hardened server provisioned in under 40 seconds.