Open in
Transfer calls
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:
- Open Voice Agents, select the agent, and open Config.
- In the prompt, add each destination, its routing condition, and whether to
use
coldorwarmmode. You do not enable a separate transfer toggle or create a custom tool. - If needed, set Advanced → Ring duration from 5 to 120 seconds.
- 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.
What happens during a warm transfer
- The agent tells the caller it is starting the transfer.
- The caller hears hold music. The caller cannot hear the target ringing or the private conversation.
- 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. - The target can ask questions before deciding. The agent answers from the original conversation and its prompt while the caller remains on hold.
- 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.
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.
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.
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. |
| 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.
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.
See Completion webhooks 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.