Human transfers

Sooner or later a caller needs a person. Unmute has one authoring shape for that, an entry under an agent’s transfers:, and two forms.

Form	What the caller experiences
cold	the agent says it is putting them through, the call moves to the person, and the agent drops out
warm	the caller waits while the agent rings the person, tells them what the call is about, and only then connects the two

On this page:

How you write it - the block, and every key it takes
The number is an environment variable - the model never sees a number
The route decides what is possible - which shape compiles where
The transfer has to be reachable - the half that is enforced
When the person does not pick up - ring_timeout and on_unavailable
Where to go next - the two routes that carry a transfer

How you write it

A transfer is a block in the transfers: list of the agent that offers it. Cold is the default. Writing brief: makes it warm, so a warm only setting cannot be written on a cold transfer:

agent.yaml

agents:
  - name: front_desk
    transfers:
      - name: send_to_billing
        to: BILLING_PHONE_NUMBER
        when: The caller asks about an invoice, a refund, or a charge they do not recognise.

      - name: escalate_to_supervisor
        to: SUPERVISOR_PHONE_NUMBER
        when: The caller is unhappy with how something was handled and asks for a manager.
        brief: |
          Lead with the caller's name and which stylist they saw.
          Say what they are unhappy about and what you already offered them.
          Ask whether they can take the call now.
        ring_timeout: 25s
        on_unavailable: return_to_caller

A transfer is defined once, by the agent that writes its block. Another agent offers it by listing the bare name, - send_to_billing. A bare name nobody defines is refused, and so are two blocks with one name.

Transfer fields

string

required

A lower snake case name, unique across the package.

string

required

The UPPER_SNAKE name of an environment variable holding an E.164 number or a sip: URI, read at call time. Declare it in secrets:. No destination is inferred.

string

The situation the model reads to decide whether to transfer. Omission supplies no trigger guidance, so write one.

string

A positive Go duration, such as 25s. Omitted means 25 seconds on Pipecat; LiveKit leaves it unset for the platform default.

string

Accepts return_to_caller or hangup. Omitted means return_to_caller. Pipecat cloud-websocket requires explicit hangup, because the original media stream cannot be reconnected.

string

Instructions for briefing the person before connecting the caller. Makes the transfer warm. Supported only on LiveKit SIP.

The number is an environment variable

The model never sees a phone number. to: names the variable that holds it, and the variable goes in secrets::

agent.yaml

secrets:
  - BILLING_PHONE_NUMBER
  - SUPERVISOR_PHONE_NUMBER

A number written in to: is refused. The refusal does not repeat the number:

agent.yaml:60: transfer "send_to_billing" has a literal to:. agent.yaml is the portable
  half of a package, so to: names an environment variable holding the number, for
  example to: BILLING_PHONE_NUMBER

The variable sits in agent.yaml rather than on the target because who this agent transfers to is the same desk whichever carrier reaches it.

The route decides what is possible

Transfers ride the platform’s own primitive. There are three different mechanisms, which is why the answer differs per route:

Route	Cold	Warm	Mechanism
LiveKit `sip`	yes	yes, the only one	SIP REFER on the caller’s existing leg, and LiveKit’s `WarmTransferTask` for the held and briefed shape
Pipecat `daily-sip`	yes, on a phone call	refused	Daily transfers the existing SIP phone leg
Pipecat `cloud-websocket`	yes, differently	refused	one request replaces the live call’s markup at the carrier
LiveKit `connector`	refused	refused	the transport carries media only, with no transfer control

Warm transfer is not supported on any Pipecat target. It requires the LiveKit sip route. Pipecat daily-sip + Twilio is the Daily shape that transfers, and the carrier is why: your carrier owns the number and hands Daily the SIP leg, so there is a real phone leg to hand on. A cold transfer there needs a Twilio connection and an active channels.phone route; a browser session has no leg and gets a named failure before the agent announces anything. You hear a transfer on a deployed agent. Both shapes hand a real phone leg to a real number, so there is no local rehearsal for either: deploy, finish the carrier setup, and place the call. The browser loop that unmute dev gives you covers the prompt, the tools and the models, and stops exactly where the phone leg starts. Read the two words in that table carefully, because they are different answers:

yes means the compiler emits it, and a deployed call performs it.
refused means the shape does not compile. The error names the connection, the transport it declares, and a route where the shape does work.

The route comes from the connection the target names, so that is what the refusal points at. A transfer a route cannot do is refused at validation, naming the connection and the transport it declares, and it never compiles into something that quietly does nothing:

pipecat: telephony warm_transfer: telephony route (pipecat, cloud-websocket, twilio) does
  not emit warm transfer: a warm handoff has to act on how the destination's leg ended,
  which on this route needs a callback endpoint you host, and hosting nothing is what
  this route is for; warm transfer compiles on (livekit, sip) trunks today. Connection
  "twilio_voice" declares transport: cloud-websocket

That last sentence is the fix: to get a warm transfer here you change the connection, not the control.

A target with no route at all

The table above is about which route does what. A target that names no connection is a separate case, and it is now refused too:

livekit: cold transfer needs a telephony Connection: it hands the caller's own phone leg to
  the destination, and a session that did not arrive by phone has no leg to hand over

This used to compile. LiveKit emitted the transfer tool, and the generated code carried a branch explaining, in a comment, that the usual cause of failure is “a session that never arrived by phone: an Agent Console run, a browser session”. The compiler knew and shipped it anyway. A Pipecat daily-sip transfer needs a Twilio connection and an active channels.phone route. A browser session has no SIP leg and gets a named failure before the agent announces a transfer.

The transfer has to be reachable

A transfer block sits in one agent’s transfers: list. Another agent offers it by listing the bare name. A bare name that no agent defines is refused at build, with the file, the line, and the fix:

agent.yaml:52: an agent names the transfer "send_to_billing", and no agent defines it;
  write it as a block under one agent, - name: send_to_billing

A transfer no agent the call can reach offers is refused too, because its number would reach .env.example and the startup check for something nothing could dial.

When the person does not pick up

ring_timeout: 25s
on_unavailable: return_to_caller

On the LiveKit sip route, no answer, a decline, voicemail, and a failed dial all come back as one failure, and on_unavailable decides what happens next. On the Pipecat cloud-websocket route, when the destination leg ends, Twilio ends the original call. A decline or no answer also ends the call after the dial timeout. No fresh agent starts without the previous conversation context. Pipecat cloud-websocket requires explicit on_unavailable: hangup; it cannot reconnect the original media stream. The agent sees only the accepted REST update as transfer_started; it does not observe whether the person answers.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Human transfers

How you write it

Transfer fields

The number is an environment variable

The route decides what is possible

A target with no route at all

The transfer has to be reachable

When the person does not pick up

Where to go next

LiveKit route

Pipecat on Twilio

​How you write it

​Transfer fields

​The number is an environment variable

​The route decides what is possible

​A target with no route at all

​The transfer has to be reachable

​When the person does not pick up

​Where to go next

LiveKit route

Pipecat on Twilio

How you write it

Transfer fields

The number is an environment variable

The route decides what is possible

A target with no route at all

The transfer has to be reachable

When the person does not pick up

Where to go next