---
title: "Transfer calls"
description: "Route callers with cold transfers or screen the destination first with a warm transfer."
---

Every phone agent has a built-in `transfer_call` action. Tell the agent in its
prompt when to transfer, which number to use, and whether the handoff should be
cold or warm.

| Mode | What happens | Use it when |
| --- | --- | --- |
| **Cold** | The caller is sent directly to the destination. The agent does not introduce the caller or confirm that anyone will answer. | Fast routing matters more than a screened handoff, or the call uses a ThunderPhone-provisioned number. |
| **Warm** | The caller waits on hold while the agent privately calls and screens the destination. The parties are connected only if the target accepts. | The target needs context before accepting, or the caller should return to the agent when nobody is available. |

If the agent omits the mode, the transfer is cold.

## Configure transfers

In the dashboard:

1. Open **Voice Agents**, select the agent, and open **Config**.
2. In the prompt, add each destination, its routing condition, and whether to
   use `cold` or `warm` mode. You do not enable a separate transfer toggle or
   create a custom tool.
3. If needed, set **Advanced → Ring duration** from 5 to 120 seconds.
4. Select **Deploy**.

With the API, `PATCH /v1/agents/{agent_id}` to stage the prompt and optional
`ring_duration_seconds`, then `POST /v1/agents/{agent_id}/deploy`. See the
[Agents API](/api-reference/agents#update-an-agent-writes-the-draft).

## What happens during a warm transfer

1. The agent tells the caller it is starting the transfer.
2. The caller hears hold music. The caller cannot hear the target ringing or
   the private conversation.
3. ThunderPhone calls the target from the VoIP number handling the call. The
   agent delivers its `screen_message`, which should identify the agent, name
   the caller, explain the reason for the call, and ask whether the target can
   take it.
4. The target can ask questions before deciding. The agent answers from the
   original conversation and its prompt while the caller remains on hold.
5. If the target accepts, the caller comes off hold and both people hear the
   short `introduction`. The agent then drops automatically. The two people
   remain connected.

If the target declines, does not answer, or reaches voicemail, ThunderPhone
removes that private call and takes the caller off hold. The agent receives the
outcome and continues the original conversation. It can take a message, suggest
another route, or make a cold transfer if the caller still wants one. A warm
transfer does not leave a voicemail. If the target asks the agent to pass along
a message, the tool result includes it as `relay_message_for_caller`.

<Note>
  If the agent's consent announcement is enabled, the transfer target hears
  that announcement before the private screening conversation begins. The
  waiting caller does not hear it a second time.
</Note>

## Prompt the agent to transfer well

Put the routing rules in the agent prompt. Use E.164 format: `+`, country code,
and the full national number, such as `+14155550123`. Specify the transfer mode
for each route and give the agent a fallback for failed warm transfers.

```text
Transfer policy

Confirm the caller's name and reason for calling before any transfer.

| Caller needs | Destination | Transfer mode |
| --- | --- | --- |
| A new purchase or plan change | +14155550123 | warm |
| Help with an existing order | +14155550124 | warm |
| The main office | +14155550125 | cold |

For a warm transfer:
- In the private screen message, identify yourself, give the caller's name and
  a one-sentence reason for the call, then ask whether the target can take it.
- Answer reasonable questions from the target using the conversation context.
- If the target accepts, introduce both people in one short sentence. Do not
  plan to speak after the introduction because you will be dropped.
- If the target declines, does not answer, or reaches voicemail, tell the
  caller what happened. Relay any message from the target, then offer to take
  a message or try another route. Do not cold-transfer unless the caller asks.
```

The agent supplies these fields when it calls the built-in action:

| Field | When used | Purpose |
| --- | --- | --- |
| `phone_number` | Always | Destination in E.164 format. |
| `mode` | Optional | `cold` or `warm`; defaults to `cold`. |
| `screen_message` | Required for warm | The opening message heard privately by the target. |
| `introduction` | Required for warm | One short line heard by both parties after the target accepts. |

You do not need to define or attach a custom tool named `transfer_call`.

## Whisper transfers

“Whisper transfer” is a common industry name for a warm transfer where the
destination hears private context before the caller is connected. In
ThunderPhone, the warm transfer's `screen_message` provides that private
briefing. The target can then ask the agent follow-up questions before accepting
or declining.

This is different from
[`POST /v1/calls/{id}/whisper`](/guides/monitor-live-calls#whisper-to-the-agent).
That endpoint lets a staff member or owner send private text guidance to the AI
agent during a live call. It does not call or brief a transfer destination.

## Requirements, limits, and testing

| Question | Answer |
| --- | --- |
| Which numbers support warm transfer? | A verified number imported through a VoIP connection that can place outbound calls. ThunderPhone-provisioned numbers support cold transfer only. If warm mode is unavailable, the action falls back to cold transfer. [Connect a VoIP provider](/guides/voip-providers). |
| Which call types support it? | Cold transfer is available on ordinary phone calls. Browser Talk, widgets, simulations, and test calls cannot test a warm handoff. Saved-agent Realtime omits `transfer_call`; inline Realtime with `call_events` can request cold transfer. |
| How do I test it? | Check routing language in Browser Talk or a simulation, then test the complete handoff on a real phone call using an eligible imported VoIP number. |
| How long does the destination ring? | `ring_duration_seconds` accepts 5–120 seconds. `null` uses 45 seconds for warm transfer and the carrier's default for cold transfer. Ordinary outbound calls default to 60 seconds. The setting does not change inbound ringing. |
| How long can the human bridge last? | Up to 60 minutes after the agent connects the two people. |
| What happens on failure? | If the target declines, does not answer, reaches voicemail, or the outbound leg fails, the caller returns to the agent with the result. The prompt should define the next step. |
| What does it cost? | There is no transfer-tool fee. Normal call charges include the warm-transfer flow through the introduction, then ThunderPhone metering stops when the AI leaves. Your carrier can continue billing the outbound transfer leg while the two people remain connected. |

## Webhooks and end reasons

The completion payload records the destination in `transfer_number` and uses
one of these end reasons:

| `end_reason` | Meaning |
| --- | --- |
| `ai_transfer` | The agent initiated a cold transfer. |
| `ai_warm_transfer` | The target accepted a warm transfer, the parties were connected, and the agent dropped after the introduction. |

A declined, unanswered, failed, or voicemail warm attempt is not a completed
transfer. The caller returns to the agent, so the eventual end reason reflects
what ends the original call.

For a successful warm transfer, the completion event and the AI call's end
reason are recorded when the introduction finishes and the AI leaves. If
recording is enabled, audio continues through the human bridge until it ends;
speech after the handoff is recorded but not transcribed. When the agent's
consent announcement is enabled, the transfer target hears it before screening
begins.

<Accordion title="Legacy completion webhook">
  A legacy single-URL webhook can delay a cold transfer for up to five minutes
  by returning `{"transfer_ready": false}` and later updating the call's
  transfer-ready state. Webhook endpoint deliveries and warm transfers do not
  use this coordination.
</Accordion>

See [Completion webhooks](/webhooks/call-complete) for the complete payload and
legacy behavior.

## Troubleshooting

### The agent makes a cold transfer instead of a warm one

Check that the call is using a verified, imported VoIP number with working
outbound routing. Warm mode is removed from the tool options for ThunderPhone
numbers and non-phone sessions. Also make the mode explicit in the prompt's
routing table.

### The target never answers

Confirm that your VoIP trunk can place outbound calls to the destination and
that its authentication and routing rules are current. Check the destination's
E.164 formatting. Increase `ring_duration_seconds` if 45 seconds is too short
for a warm transfer.

### The target reaches voicemail

Warm transfers do not leave a voicemail. The caller comes off hold and the
agent receives a `voicemail` result. Tell the agent in its prompt whether to
take a message, try another destination, or offer a cold transfer.

### The caller does not get the target's message

Tell the agent to relay `relay_message_for_caller` before offering next steps.
That field is present only when the target declines and asks the agent to pass
something along.

### A cold transfer waits before connecting

If you use the legacy single-URL webhook, check whether it returned
`{"transfer_ready": false}`. The caller hears hold music while ThunderPhone
waits. Update the call's transfer-ready state when the destination is prepared.

### Staff whispering does not start a transfer

Live-call whispering only coaches the AI. Add transfer instructions to the
agent prompt and let it call `transfer_call`. See
[Monitor live calls](/guides/monitor-live-calls).