force_fronter_audio_stop: silencing fronter audio playback after a handoff

When a fronter plays a recorded clip, a soundboard line, or a hold prompt and then hands the call to a closer, that audio can keep playing in the fronter's session after they are gone. It is harmless to the customer but messy for the fronter, and it can confuse the next call if it bleeds over. The force_fronter_audio_stop function lets the closer reach back into the fronter's session and stop it.

How it finds the right session

Like its sibling function for leaving a 3-way, this one is an Agent API command run with the closer as the named agent_user. It will not act on that named agent. Instead it looks for another user session that is on a call with the same Lead id the named agent is on, finds the Fronter, and sends a stop signal to whatever audio_playback is running there. The customer never hears a jump; the change happens inside the fronter session.

Value options for split floors

The value tells the function where to search. LOCAL_ONLY stays on the local cluster. LOCAL_AND_CCC checks local first and then a remote CCC. CCC_REMOTE is for when the closer is not on this cluster, and it accepts an optional lead_id to aim the search. The order is always local-first, so on a single-server site you can keep it simple with LOCAL_ONLY and never think about the rest.

flowchart TD
  A[Fronter audio still playing] --> B[Closer calls force_fronter_audio_stop]
  B --> C{Value chosen}
  C -->|LOCAL_ONLY| D[Search local cluster]
  C -->|LOCAL_AND_CCC| E[Local then remote CCC]
  C -->|CCC_REMOTE| F[Remote cluster]
  D --> G[Match fronter session on same lead]
  E --> G
  F --> G
  G --> H[Send stop to audio playback]
  H --> I[Fronter session goes quiet]

Reading the responses

A clean run returns a SENT response naming the session it acted on. Several outcomes are not errors so much as facts about the call. If there is no second session on the lead, you get no fronter session found or no fronter found. If the fronter session exists but nothing is playing, you get a no audio playing in other agent session response, which simply means there was nothing to stop. Treat that as a success in your logic, not a failure, because the goal was silence and silence is what you have. The response strings also include the session and lead identifiers, so when you are debugging a floor with many concurrent calls you can confirm the command landed on the session you expected and not on some other agent who happened to be near the same lead.

One real gotcha: this function is permission gated. If the calling user lacks the right to use it, you get a clear permission error rather than a silent no-op, so the user account driving your automation needs the function enabled. The named agent also has to be logged in and on a phone call for the lookup to work at all.

In practice you wire this right after force_fronter_leave_3way so the fronter both leaves the conference and goes quiet in one motion. Together they make a handoff feel instant for the Closer. The broader handoff flow is covered in our transfers and closers guide, and the companion leave function is broken down in force_fronter_leave_3way.

If hand-rolling these API calls is more than you want to own, a managed dialer handles the plumbing. See our pricing for what that costs.