AI-to-Human Handoff

Escalate a live call from an AI agent to a human without a drop in audio and without a new call. This page is the telephony-plane view of a handoff. It covers what the SIP gateway does on the wire when you call transfer(...), how the sid survives, and how the gateway rings a human — on a browser softphone or a real deskphone — so that the human takes over the media. For the product-level model and the bidirectional (bot ⇄ human) framing, start at Handoffs. This page is the mechanics underneath it. A handoff can be driven in two ways over the same gateway. In the first way, you (your app, or an operator dashboard) call transfer(...) on the SDK. In the second way, the AI agent itself decides mid-conversation and calls a built-in telephony tool: transfer_call, route_to_skill, warm_transfer / complete_transfer, or consult / consult_transfer / consult_cancel. The tool path needs no operator config. Both ways land on the same B2BUA and preserve the same sid. The tool path only lets the model pick the moment and the style. These tools are the same operations exposed to ISV apps as CSTA verbs — see CTI call control.

The one call keeps its sid

A call is a SIP dialog with two legs, caller and agent. A back-to-back user agent (B2BUA) in the SIP gateway holds them together. The sid names that dialog and is the universal key. The same value addresses the CDR, the recording, the analytics segments, and the media tracks. A handoff re-points the agent leg only. The caller leg never moves. The caller hears uninterrupted audio, and the sid is unchanged before, during, and after.

   caller leg  ─────────┐
   (never moves)        │      ┌─── agent leg ─▶  AI agent      segment 1 (handler=ai)
                   B2BUA ┤─────┤
   same sid  ───────────┘      └─── agent leg ─▶  human agent   segment 2 (handler=human)
                              (only this leg re-points)

The dialog is preserved, so the call-events pipeline emits a transfer transition on the existing sid, not an END. Downstream, the pipeline folds the call into multiple segments under one sid. The segments are split by handler: AI or human. This gives the ”12s with the bot, 4m18s with a human” breakdown. See Call lifecycle for the full event sequence. See Sessions, calls, tracks & streams for the object model.

When is a sid created, and when is it preserved? The engine mints a sid once, when the call first exists: at the inbound INVITE, or when you call calls.originate() outbound. Every handoff after that preserves it. You never create a sid for a transfer. You pass the one that you already hold.

Two mechanisms, picked by target

The SDK exposes one method, transfer(...). The gateway chooses the mechanism from the field that you set:

You pass	Mechanism	Media stays on our plane?
`agent: "<id>"`	In-place re-attach of the agent leg (skill-queue router or a named human/AI agent)	Yes
`to: "<E.164>"`	SIP `REFER` — ask the far end to re-target its leg to a phone number or PBX	No (once accepted, off-net)

Set exactly one of agent / to per transfer. A bare string is shorthand for { to }.

Escalate to a human (re-attach)

Route the caller into the skill-queue router (ACD). The ACD rings an available human and bridges them in on accept. Or transfer to one named person. The caller leg holds. The agent leg re-points to the human once they answer.

TypeScript
Python

import { Voice } from "@clutchcall/sdk/voice";

const v = new Voice({
  baseUrl: "https://engine.clutchcall.dev",
  apiKey:  process.env.CLUTCHCALL_CREDENTIALS!,
  orgId:   "org_abc",
});

// A call is already live with a triage bot; you hold its sid.
const call = await v.calls.get({ sid });

// Escalate to the human support queue — the ACD picks the agent.
await call.transfer({ agent: "human-support" });

from clutchcall.voice import Voice

v = Voice(
    base_url="https://engine.clutchcall.dev",
    api_key=os.environ["CLUTCHCALL_CREDENTIALS"],
    org_id="org_abc",
)

call = v.calls.get(sid=sid)

# Escalate to the human support queue — the ACD picks the agent.
call.transfer(agent="human-support")

The human who answers can be on a browser softphone or a real SIP deskphone/softphone. The accept signal is unified, so your transfer code is identical either way. When the human claims the call, the gateway dials their endpoint: an INVITE to the registered contact, or a call out through a trunk for a PSTN callback. The gateway waits for the 200 OK and bridges the leg into the same B2BUA. PBX & ACD explains how agents register, get rung, and claim a call, and covers ring strategy and glare handling.

Transfer off-net via SIP REFER

When the target is a phone number (a PSTN destination or another PBX), the gateway performs a SIP REFER (RFC 3515). This is the standard request that asks the far end to re-target its leg. You do not build the REFER yourself. Pass to, and that is enough.

TypeScript
Python

await call.transfer({ to: "+15557654321" });  // → SIP REFER
await call.transfer("+15557654321");          // shorthand, same thing

call.transfer(to="+15557654321")  # → SIP REFER
call.transfer("+15557654321")     # shorthand, same thing

A blind REFER to a PSTN number hands the caller to the carrier and off our media plane. Once the far end accepts, you no longer control that audio. Recording, barge-in, supervise, and re-attach are gone for the rest of the call. When you want to keep those, prefer transfer({ agent }) to a human on a softphone or deskphone. That keeps the media on our plane.

Handoff tools the AI agent calls itself

Everything above is the operator-driven view: your code holds the sid and calls transfer(...). But most escalations should be the agent’s own decision, made in the flow of the conversation. Every AI agent gets a built-in telephony toolset with no operator config. The runtime advertises these tools to the model automatically. When the model calls one, the gateway runs the exact same B2BUA operation on the live sid. These are first-class runtime tools, not user-declared functions. See Tool calling for how the toolset is advertised, and how an operator tool of the same name overrides a built-in. There are three transfer styles. The right one is a caller-experience choice. Ask two questions: does the caller hear the handoff, and does the AI stay on the line?

Tool	What the caller hears	AI stays or leaves	When to use
`transfer_call`	A brief pause, then the destination. No handoff is spoken.	Leaves immediately	The fastest path. Use it when you know exactly where the caller should go (a queue URI, a PSTN number, another PBX) and no context needs to pass by voice.
`route_to_skill`	Queue treatment (ringback / hold audio) until a human answers	Leaves (steps out to the ACD)	“Get me a human” with no specific number. Hand to a human skill/queue and let the ACD pick the agent.
`warm_transfer` → `complete_transfer`	Everything. The AI and the human brief each other in a shared conference, and the caller is included.	Stays through the brief, then leaves on `complete_transfer`	A smooth, human-feeling handoff. The caller hears “I’ve got Priya here, she can take it from…”. Context passes out loud.
`consult` → `consult_transfer` / `consult_cancel`	Nothing. The caller is held (hold audio) while the AI checks privately.	Stays; can return to the caller with `consult_cancel`	Check that a human is available, or get an answer, before you commit the caller. If it works out, `consult_transfer`. If not, `consult_cancel` and keep talking to the caller.

destination for transfer_call, warm_transfer, and consult accepts a skill name, an extension, a SIP URI (sip:queue@pbx.example.com), or a PSTN number in E.164 (+15551234567). transfer_call also accepts a tel: URI. This is the fastest exit. The AI hands the caller away and drops off the call in one step. Under the hood, this is a SIP REFER, the same as an operator transfer({ to }). Nothing is spoken to the receiving party first.

string

required

Where to send the caller: a skill name, an extension, a SIP URI, a tel: URI, or an E.164 number.

string

Optional Referred-By identity to present on the REFER. Defaults to the trunk identity.

Queue to a human skill — `route_to_skill`

Send the caller to a human skill/queue (the ACD) without a named person or number. The AI steps out. The skill-queue router rings an available human and bridges them onto the same sid.

string

The target skill/queue. Omit it to use the agent’s default escalation skill.

Warm (attended) — `warm_transfer` then `complete_transfer`

The AI dials the destination and joins a conference, so that it can speak the handoff. The caller hears everything, and the AI stays live. This is the transfer that feels human.

AI calls warm_transfer { destination }

The gateway dials destination and joins it into a conference with the caller. The caller hears the ring. Then all three parties are connected: caller, human, and AI.

The AI briefs the human, out loud, in the conference

“This is Sam calling about order 4471, they need a refund exception.” The caller hears the whole brief, so nothing feels like it happened behind their back. The human can ask the AI (or the caller) questions before they accept.

AI calls complete_transfer { }

The AI leg stops. The caller and the human stay connected on the same sid. The gateway records a transfer transition, and analytics opens a new human segment.

Private consult — `consult` then `consult_transfer` / `consult_cancel`

This is an attended, one-to-one check with a third party. The caller does not hear it. The caller is effectively on hold while the AI confirms availability or gets an answer. The AI then commits or backs out.

AI calls consult { destination }

The gateway places the caller on hold (hold audio). The AI dials destination on a private leg. The caller hears none of the consult conversation.

The AI speaks privately with the consulted party

“I have a caller who needs a refund exception on order 4471 — can you take it?” Only the AI and the consulted party are on this leg.

Commit — consult_transfer { }

This connects the caller to the consulted party and drops the AI out. The caller comes off hold already bridged to the human.

…or back out — consult_cancel { }

This hangs up on the consulted party and returns the AI to the caller. The caller comes off hold. Use this when the human cannot take the call. The AI keeps handling the call and can try another path.

Transfer-rule policy still applies. Whichever tool the model calls, the transfer passes the realm’s transfer-rule policy. A denied cross-realm transfer returns a structured error that the model can react to: apologize, try route_to_skill, or offer a callback. It does not fail silently.

Supporting in-call tools

The same built-in toolset gives the AI the rest of the mid-call controls. The AI can shape the caller experience around a handoff:

Tool	Params	What it does
`hold_call` / `unhold_call`	—	Park the caller on hold audio, and bring them back.
`disconnect_call`	`reason?`	End the call. The gateway writes `reason` to the CDR.
`send_dtmf`	`digit` (`0-9*#A-D`), `duration_ms?` (default `100`), `mode` (`rfc2833`\|`inband`)	Play DTMF into the call — e.g. to navigate a downstream IVR before or after a transfer.
`request_supervisor`	`reason`, `urgency` (`low`\|`medium`\|`high`)	Ask a supervisor to monitor, whisper, or barge in. The caller leg does not move.

What happens on the wire

You call transfer(sid, …)

The control-plane API forwards the request to the SIP gateway over its correlated RPC channel. The gateway looks up the live dialog by sid.

The agent leg is re-pointed, REFERred, or conferenced

For agent: / route_to_skill, the gateway re-attaches the agent leg in the B2BUA. It dials the human endpoint, or hands the call to the skill-queue router. For to: / transfer_call, the gateway issues a SIP REFER toward the leg that you forward. For warm_transfer, the gateway joins the destination into a conference with the caller. For consult, it holds the caller and opens a private leg to the consult target.

A transfer lifecycle event fires on the same sid

The gateway emits a transferred transition. When the gateway is the receiver of a peer REFER, it auto-acknowledges with 202 Accepted. The gateway emits no END — the sid lives on. Recording continues. Analytics opens a new segment tagged with the new handler (AI or human).

The far end takes over

For a re-attach, the human’s 200 OK completes the bridge. Audio then flows to the new agent leg. For an off-net REFER, the referred party accepts, and the caller now talks to the external number.

Peer-initiated REFER (inbound)

The reverse also happens: a remote party sends us a REFER. This is a carrier or upstream PBX asking us to forward a call. The gateway auto-answers it with 202 Accepted and records a transferred lifecycle event on the sid. The transfer then shows up correctly in traces and CDRs.

Honest status — execution of the outbound leg from a peer REFER. We acknowledge an incoming REFER today. But the automatic placement of the new outbound leg that it asks for — following the referred-to target end to end — is partially in progress. Your topology may depend on upstream-initiated blind or attended transfer to drive a fresh outbound call. If so, validate it against your carrier in staging before you rely on it. Operator-initiated transfer (you calling transfer(...)) and off-net REFER from us are the fully supported paths.

Bot ⇄ human re-attach on the media plane

For an on-plane handoff (agent:), the media stays on our transport the whole time. This makes bot → human → bot bouncing possible on one sid:

The caller’s audio is carried as a caller-audio track keyed on the sid. The human agent takes over: they pick up that track and inject their mic into the caller’s egress. Subscription is by sid, not by a fixed shard. The human can therefore live on a different core or host and still hear the caller, with no central funnel.
To hand back to an AI agent, use the same transfer({ agent }) primitive with an AI agent id. The bridge re-points in place. The sid is unchanged, and the call remains one continuous record.

// Human is done; hand back to an automated wrap-up agent.
await call.transfer({ agent: "post-call-summary" });

Human-agent return audio (browser softphone). The human agent’s mic uplink into the caller is live. The downlink — the human hearing the caller over the media-over-QUIC track in the browser softphone — is still being hardened: the caller-audio origin publish needs to be bridged into the relay fan-out. If you stand up browser softphone agents today, validate the return-audio path in staging. Real SIP deskphone/softphone agents are not affected. Their media rides the normal RTP bridge.

Handoffs (concept)

The product model: AI ⇄ human, warm handoff, sid preservation.

Tool calling

How the built-in telephony toolset is advertised to the AI agent.

CTI call control

The same transfer / consult operations as CSTA verbs for ISV apps.

PBX & ACD

How the skill-queue router rings and claims human agents.

Call lifecycle

Every event that a call emits, including transfer transitions.

SIP trunking

The trunk edge that REFER rides out over for off-net transfers.

Support agent with handoff

A full inbound bot that escalates to a human, end to end.

Transfer to a human

Copy-paste transfer snippet.

Build a Contact Center

The one call keeps its sid

Two mechanisms, picked by target

Escalate to a human (re-attach)

Transfer off-net via SIP REFER

Handoff tools the AI agent calls itself

Blind — `transfer_call`

Queue to a human skill — `route_to_skill`

Warm (attended) — `warm_transfer` then `complete_transfer`

Private consult — `consult` then `consult_transfer` / `consult_cancel`

Supporting in-call tools

What happens on the wire

Peer-initiated REFER (inbound)

Bot ⇄ human re-attach on the media plane

Handoffs (concept)

Tool calling

CTI call control

PBX & ACD

Call lifecycle

SIP trunking

Support agent with handoff

Transfer to a human

​The one call keeps its sid

​Two mechanisms, picked by target

​Escalate to a human (re-attach)

​Transfer off-net via SIP REFER

​Handoff tools the AI agent calls itself

​Blind — transfer_call

​Queue to a human skill — route_to_skill

​Warm (attended) — warm_transfer then complete_transfer

​Private consult — consult then consult_transfer / consult_cancel

​Supporting in-call tools

​What happens on the wire

​Peer-initiated REFER (inbound)

​Bot ⇄ human re-attach on the media plane

​Related

Handoffs (concept)

Tool calling

CTI call control

PBX & ACD

Call lifecycle

SIP trunking

Support agent with handoff

Transfer to a human

The one call keeps its sid

Two mechanisms, picked by target

Escalate to a human (re-attach)

Transfer off-net via SIP REFER

Handoff tools the AI agent calls itself

Blind — `transfer_call`

Queue to a human skill — `route_to_skill`

Warm (attended) — `warm_transfer` then `complete_transfer`

Private consult — `consult` then `consult_transfer` / `consult_cancel`

Supporting in-call tools

What happens on the wire

Peer-initiated REFER (inbound)

Bot ⇄ human re-attach on the media plane

Related