You can hand a live call between an AI agent and a human, in either direction. The audio does not drop. The identifier that addresses the call does not change. A handoff swaps who is on the far end of the media bridge. It does not stop and re-create the call. The same sid addresses the call before, during, and after the handoff. Every recording, transcript, and analytics row keyed on that sid stays one continuous story. You will make three moves in practice:

​
Everything hangs off one sid

A call is a SIP dialog with two legs: caller and agent. A B2BUA (back-to-back user agent) in the SIP gateway holds the two legs together. The sid names that dialog. When you hand off, only the agent leg re-points. The caller leg never moves. From the caller’s perspective, the audio path continues without interruption.
Because the sid survives, the call events pipeline emits a TRANSFER_INITIATED (or REFER_RECEIVED) transition, not an END. Downstream systems fold the call into multiple segments under one sid. The segments split by handler: AI or human. This gives you a correct ”12s with the bot, 4m18s with a human” breakdown, not two unrelated calls. See Sessions, calls, tracks & streams for the object model and Call traces for the segment rows.

​
AI → human

The bot decides that it needs a person. Examples: an intent that it cannot satisfy, a compliance trigger, or an explicit “let me talk to someone”. You transfer the live call to a human. There are two options:
  • To a skill queue — route the caller into the ACD (skill-queue router). The ACD rings an available human agent and bridges them in on accept. Use this option when any qualified agent is acceptable.
  • To a specific human — transfer to a named agent, a browser softphone, or a phone number. Use this option for warm escalations to a known owner.
The human who answers can be a browser softphone or a real SIP deskphone/softphone. The accept path is unified, so your transfer code is identical in both cases. PBX & ACD covers how the system rings agents and how agents claim a call.
Warm handoff / screen-pop. The product thesis for regulated verticals is this sequence: the AI does intent, qualification, auth, and compliance capture first. Then a context bundle screen-pops to the human before audio cuts in. The routing and accept legs are shipped today. Your application layer assembles the rich context payload that travels with the transfer. You build the context bundle. There is no turnkey field for it yet.

​
Human → AI

The reverse move re-attaches an AI agent to a live call. Use it to deflect a queued caller to a self-service bot, to drop into an after-hours agent, or to run automated wrap-up. It is the same transfer({ agent }) call. You name an AI agent instead of a human queue. The bridge re-points in place, and the sid does not change. A call can bounce bot → human → bot and stay one record.

​
Transfer off-net via SIP REFER

When you transfer to a phone number (a PSTN destination or another PBX), the gateway performs a SIP REFER. This is the standard way to ask the far end to re-target its call leg. You do not construct the REFER yourself. Pass to, and that is enough. A bare string is shorthand for { to }.
The gateway records the transfer as a REFER_RECEIVED lifecycle transition on the same sid. Rule of thumb: to → SIP REFER (off-net); agent → in-place re-attach (on our media plane). In both cases, the original sid continues to address the call.
A blind REFER to a PSTN number hands the caller to the carrier and off our media plane. After the far end accepts, you no longer control that audio. Prefer transfer({ agent }) to a human on a softphone or deskphone when you want to keep recording, barge-in, and re-attach available for the rest of the call.

​
Bot ⇄ human re-attach, step by step

1

Hold the sid

You get a sid from calls.originate() (outbound) or from the inbound call webhook. It is the only identifier that you need for every later step: transfer, hang up, fetch recordings, and read analytics.
2

Decide the target

The target is a human queue (agent: "human-support"), a specific human, an AI agent, or an off-net number (to). Give exactly one of agent / to per transfer.
3

Transfer

Call transfer(...). The caller leg stays in place. The agent leg re-points. The caller hears continuous audio. You can optionally play hold media while the queue rings.
4

It re-attaches, it does not restart

A TRANSFER_INITIATED / REFER_RECEIVED event fires on the same sid. Recording continues. Analytics opens a new segment tagged with the new handler (AI vs human). No new call is created.

​
Honest status

  • AI → human transfer — shipped. Routing into the queue and human accept work end to end (a prior transfer-teardown crash is fixed).
  • Human → AI re-attach — shipped, same transfer({ agent }) primitive.
  • sid preservation across handoffs — shipped; segments fold under one sid by handler.
  • Human-agent two-way audio (browser softphone). The agent’s mic uplink is live. The downlink leg (the human hears the caller over the media-over-QUIC track) is still being hardened. The caller-audio origin publish must be bridged into the relay fan-out. If you stand up browser softphone agents now, validate the return audio path in staging. Real SIP deskphone agents are not affected.
  • Warm screen-pop context payload — application-level today (see the Note above), not a turnkey feature.

AI-to-Human Handoff

See the telephony-plane view of escalation and accept.

PBX & ACD

Learn how the skill-queue router rings and claims human agents.

Support agent with handoff

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

Transfer to a human

Copy a ready transfer snippet.

Call lifecycle

See every event that a call emits, including transfers.

Sessions, calls, tracks & streams

Learn why the sid is the one identifier that matters.