Whisper to an agent mid-call

Voiceagent whisper and call coaching

One-way audio that only the agent's leg can hear.

conferencecoach

The claim

A supervisor joins a live call as a coach. The agent hears them, the customer does not, and the call carries on. Nothing is transferred and nobody is put on hold.

Why it holds

Coaching is aimed at a call, not at a room. That is the difference between whispering to an agent and being a third person in the meeting.

How it works

join_conference takes a coach field, and it holds the call ID of a participant already in the conference.

FunctionResult("Putting you through.").join_conference(
    name=ROOM,
    coach=call_id,      # the one leg that hears the supervisor
    muted=True,         # silent to everyone else
    beep="false",       # arriving without announcing it
    start_on_enter=False,
)

muted and coach are doing different jobs and both are needed. muted keeps the supervisor out of the room’s mix; coach mixes them into one leg anyway. Set muted alone and the supervisor is silent to everyone including the agent. Set neither and the customer hears a stranger.

beep is "false" because the default announces an arrival, which tells the customer that something has changed.

start_on_enter is false so a supervisor arriving does not start anything, and end_on_exit stays at its default of false so leaving does not end the customer’s call. The SDK helper omits fields already at their default, so end_on_exit is absent from the emitted document rather than present and false.

The handler checks two things before it emits anything, in that order. First who is asking: the caller’s number has to be on a supervisor list, because reaching this console is not permission to listen to a customer. Then whether the named agent is on a call, since joining with no coach target is a plain participant the customer hears.

Limitations

coach needs a call ID, and this recipe keeps a hard-coded map of them. In production those come from the conference status callbacks, which is build-a-conference-call.

The caller check is caller ID, and caller ID can be spoofed. It is a floor, not a door. require-verification-before-unlocking-tools is the same shape with a PIN behind it.

Whispering is audible to the agent, so it interrupts them. There is no signal to the agent that a supervisor has arrived beyond the supervisor speaking.

What to change first

Delete coach and keep muted: True. The supervisor is now in the room and audible to nobody. Delete muted too and the customer hears them.

python/app.py

"""Whisper to an agent mid-call.

A supervisor joins the conference as a coach. The agent hears them; the customer
does not.

`coach` is the mechanism, and it takes the call ID of a participant already in
the room. That is the whole trick: coaching is aimed at a call, not at the
conference, so the platform knows which one leg to mix the supervisor into.

The supervisor's leg is muted to the room. Coaching audio is not muting's
opposite: without `coach`, an unmuted supervisor is simply a third person in
the meeting.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

# the SDK does not read .env for you
load_dotenv()

ROOM = os.getenv("CONFERENCE_NAME", "support-floor")

# Who may enter a live call. A number that reaches this console is not
# authorisation on its own: ANI is spoofable, so this is a floor rather than
# a door. require-verification-before-unlocking-tools is the version with a
# PIN behind it.
SUPERVISORS = {"+15550100777", "+15550100778"}


def calling_number(raw_data):
    """The caller, preferring state this application controls.

    `global_data` holds what your own handlers wrote, so a check against it is
    a check against something you own. The top-level field is the fallback:
    which of the two the platform populates is not settled by any source we
    hold, so this reads both rather than betting on one.
    """
    data = raw_data or {}
    scoped = data.get("global_data") or {}
    return scoped.get("caller_id_num") or data.get("caller_id_num") or ""

# Who is on the floor. A real deployment reads this from the platform's
# conference status callbacks; see build-a-conference-call.
ON_CALL = {
    "dana": "CA1111111111111111111111111111aaaa",
    "reza": "CA2222222222222222222222222222bbbb",
}


class SupervisorAgent(AgentBase):
    def __init__(self):
        super().__init__(name="supervisor", route="/supervisor")
        self.prompt_add_section(
            "Role",
            "You are the console a supervisor talks to. Ask which agent they "
            "want to coach, then put them through.",
        )

    @AgentBase.tool(
        name="coach_agent",
        description=(
            "Put the supervisor into an agent's live call as a coach, heard "
            "only by that agent. Use this when they name an agent to help."
        ),
        parameters={
            "type": "object",
            "properties": {
                "agent": {
                    "type": "string",
                    "description": (
                        "The agent's first name, lowercase, such as 'dana'."
                    ),
                }
            },
            "required": ["agent"],
        },
    )
    def coach_agent(self, args, raw_data):
        # Check who is asking before resolving who they want. Reaching this
        # agent is not permission to listen to a customer.
        caller = calling_number(raw_data)
        if caller not in SUPERVISORS:
            return FunctionResult(
                "NOT_AUTHORISED: this number is not a supervisor line. Say "
                "you cannot connect them and end the call."
            )
        who = (args.get("agent") or "").strip().lower()
        call_id = ON_CALL.get(who)
        if not call_id:
            # Coaching a call that is not there would join the supervisor as
            # an ordinary participant, audible to the customer.
            return FunctionResult(
                f"NOT_ON_A_CALL: {who or 'that agent'} is not on the floor. "
                f"Say who is available ({', '.join(sorted(ON_CALL))}) and ask "
                f"again."
            )
        return FunctionResult(
            f"Putting you through to {who}. They can hear you; the caller "
            f"cannot."
        ).join_conference(
            name=ROOM,
            # aimed at one leg, which is what makes this coaching
            coach=call_id,
            # silent to the room; only the coached leg hears the supervisor
            muted=True,
            # a supervisor arriving must not announce itself to the customer
            beep="false",
            # and leaving must not end the customer's call
            end_on_exit=False,
            start_on_enter=False,
        )


agent = SupervisorAgent()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

Point a supervisor-only number’s SWML webhook at https://<user>:<password>@<your-host>/supervisor/, and put the supervisors’ own numbers in SUPERVISORS.

Verify it

No network, no account:

python verify.py          # from the recipe folder, not python/

It renders the SWML and runs the handler, asserting:

nothing in the document joins a conference; only the handler does
the emitted join_conference carries coach set to that agent’s call id
the supervisor is muted and joins with beep: "false"
start_on_enter is false, and end_on_exit is absent, which is its default
a second agent resolves to a different call id, so the mapping is real
three ways of naming an agent who is not on a call are refused, and the refusal names who is available
three callers who are not supervisors are refused before any lookup happens

Report an issue