transfer_call tool it invokes when the caller asks for a human or the request clearly needs one. Transfers apply to phone calls only.
Two modes decide what the handoff feels like:
Prerequisites
- A phone number bound to your agent, answering inbound calls — see Inbound calls.
- The number must support transfers — numbers purchased from the platform inventory (
provider: "twilio") do; see Phone numbers.
Configure a destination
In the console
On the agent’s Phone page, under Inbound calls, turn on Call transfer. Give the destination a name, enter its phone number, and pick the transfer mode — choosing Warm adds a handoff choice (ask the human to accept first, or connect immediately after the briefing). Like every config edit, the change lands in the agent’s draft and takes effect on live calls after you publish.Through the API
Transfer destinations live in theconversation section of the agent config, as transfer_destinations. An empty list disables transfers; only one destination is supported for now — a longer list is rejected.
Destination numbers must be E.164 and are limited to a set of supported countries — a number outside the list is rejected with
422 Unprocessable Entity and an error naming the allowed country codes. The transfer card in the console shows the current list.
How the agent decides to transfer
Configuring a destination is what enables the built-intransfer_call tool — there is no separate switch, and an empty destination list removes the tool. Unlike the toggled system tools, you won’t find it in the tools config section; it ships automatically on phone sessions whenever a valid destination exists.
The built-in instructions are conservative: the agent transfers only when the caller asks for a person, or when the request clearly needs one and the agent cannot help further — never preemptively for questions it can answer itself.
What happens on a cold transfer
The agent tells the caller it is transferring them, and once that sentence finishes playing the call is handed to the carrier. The caller hears a dial tone while the destination rings; the agent drops out and its session ends at the handoff. If the handoff is refused — the destination is unreachable, or the number doesn’t support transfers — the agent stays on the line, apologizes, and keeps helping. It can attempt the transfer again later.What happens on a warm transfer
1
The caller goes on hold
The agent asks the caller to hold for a moment — in the session’s language —
and hold music starts.
2
The platform dials your human agent
A separate, private consult call rings the destination for up to 30 seconds.
It presents the number the caller originally dialed as caller ID, so your
team sees a number they recognize.
3
The agent briefs the human
The agent greets the human and relays short third-person notes on who is
calling and what they need, generated from the conversation so far. The
caller hears none of this.
4
The calls merge
With
warm_connect: "confirm" the merge waits for the human to agree; with
direct it happens right after the briefing. The hold music stops, the
human joins the caller, and the agent leaves without another word.Limitations
- Phone calls only — web and SDK sessions have no phone leg to hand off, so the
transfer_calltool never ships for them. - Transfer-capable numbers — the number the caller dialed must be a
twilio-provider number. - One destination — each agent supports a single transfer destination for now.
- Supported countries — destination numbers are limited to an allowlist of country codes.
Billing
Transferred call time is metered separately from agent time, with cold and warm transfers each billed at their own per-minute rate. The standard agent rate applies only while the agent itself is on the call — it stops at the handoff for cold transfers and at the merge for warm transfers, and the connected call is metered as transfer minutes from that point on.Going further
Inbound calls
Bind a number and put your agent on the phone.
Phone numbers
Number management, providers, and agent bindings.
System tools
The other built-in capabilities, like hanging up.
Conversation history
Review transcripts and recordings of transferred calls.