Whisper a summary to the agent before connecting the caller

Voicewarm transfer with agent whisper

Compose a bounded summary, play it to the agent, then join the caller.

Also called warm transfer, agent whisper, announce the caller before connecting

transferconference

The claim

The receiving agent picks up and hears a short briefing about the caller. Only then are the two legs joined. The caller hears hold audio throughout and never hears the briefing.

Why it holds

This is the difference between a transfer and a handoff. A transfer moves a call; a handoff moves a call and what is known about it.

How it works

connect takes a confirm, which runs on the answering leg after it picks up and before the bridge completes.

{"connect": {
  "to": "+15550100001",
  "confirm": [{"play": {"url": "say:Call from Dana about a refund."}}],
  "confirm_timeout": 20
}}

confirm takes either a URL returning a document or an array of SWML methods inline. Inline is right here, because the briefing is built from state the agent already holds and there is nothing to fetch.

Placement is the whole mechanism. The same play in main would be heard by the caller, because main is the call. Inside confirm it belongs to the leg being dialled.

FunctionResult.connect() takes no confirm, so the verb is built by hand and handed over with execute_swml. That is the same shape transfer-a-call-without-losing-context uses. It is also why the verifier asserts JSON keys rather than the SDK method behind them.

The briefing is assembled from a fixed tuple of fields. Which of them reach a colleague is decided in code, not by the model. That excludes fields outside BRIEFED. It does not redact anything inside them: whatever the model put in reason is read aloud as it stands.

A transfer with nothing collected is refused. An agent who answers to silence after being promised a briefing is worse off than one who was never promised anything.

Limitations

confirm is one-way. The agent hears the briefing and cannot answer it, so there is no accept or reject here. Making the handoff refusable means a prompt inside the confirm and a branch on the result.

confirm_timeout bounds how long the platform waits. A briefing longer than it is cut off, and a long summary is the usual cause.

What to change first

Move the play out of confirm and into main, immediately before the connect. The briefing is now read to the caller, who learns what you think their reason is. Put it after the connect instead and it does not play at all until the far leg ends.

python/app.py

"""Brief the human before the bridge completes.

The receiving agent hears a summary of the caller before the caller can hear
anything. `connect` takes a `confirm`, which runs on the answering leg once it
picks up and before the two legs are joined.

`confirm` can be a URL or an array of SWML methods inline. Inline is used here
because the briefing is built from state the agent already has, so there is
nothing to fetch.

Whatever the confirm plays is private to the answering leg. That is the whole
point: the caller is still listening to hold audio while the agent is told who
is on the line.

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()

HUMAN = os.getenv("HUMAN_NUMBER", "+15550100001")

# What the briefing is allowed to mention. This excludes whole fields; it does
# not redact within one, so a value the model wrote into `reason` is spoken as
# it stands.
BRIEFED = ("caller_name", "reason", "account_status")


def briefing_from(state):
    """One sentence, built from collected state and nothing else."""
    name = state.get("caller_name") or "an unidentified caller"
    reason = state.get("reason") or "an unstated reason"
    status = state.get("account_status")
    line = f"Call from {name} about {reason}."
    if status:
        line += f" Account is {status}."
    return line


class IntakeAgent(AgentBase):
    def __init__(self):
        super().__init__(name="intake", route="/intake")
        self.prompt_add_section(
            "Role",
            "You take the caller's name and what they need, then put them "
            "through to a person.",
        )

    @AgentBase.tool(
        name="transfer_to_human",
        description=(
            "Put the caller through to a person. Use this once you have their "
            "name and what they are calling about."
        ),
        parameters={"type": "object", "properties": {}},
    )
    def transfer_to_human(self, args, raw_data):
        state = (raw_data or {}).get("global_data", {}) or {}
        if not state.get("caller_name") or not state.get("reason"):
            # A briefing with nothing in it is worse than no briefing: the
            # agent takes the call expecting context and gets none.
            return FunctionResult(
                "NOT_READY: get the caller's name and what they need, save "
                "them, then transfer."
            )
        # Only the fields chosen above travel into the briefing.
        briefed = {k: state[k] for k in BRIEFED if k in state}
        # FunctionResult.connect() takes no confirm, so the verb is built by
        # hand and handed over as SWML. Assert the keys, not the helper.
        return FunctionResult("Putting you through now.").execute_swml({
            "version": "1.0.0",
            "sections": {
                "main": [
                    {"connect": {
                        "to": HUMAN,
                        # spoken to the answering leg, before the caller is
                        # joined, so the caller never hears it
                        "confirm": [
                            {"play": {"url": f"say:{briefing_from(briefed)}"}}
                        ],
                        "confirm_timeout": 20,
                    }}
                ]
            },
        })


agent = IntakeAgent()

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 phone number’s SWML webhook at https://<user>:<password>@<your-host>/intake/.

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 connects; only the handler does
the emitted connect carries the briefing inside confirm, with a timeout
the connect is the whole of the emitted SWML, so nothing plays to the caller
the three chosen fields are spoken, and two sensitive ones in the same state are not
a missing field degrades the sentence instead of breaking it
three incomplete intakes are refused rather than transferred

Report an issue