Transfer Call tool

The transfer call tool lets an assistant route an active phone call to a phone number or Session Initiation Protocol (SIP) URI. Use it to connect a caller with a person, department, or external phone system based on the conversation. To move a call between assistants, use the handoff tool instead; handoff works with standalone assistants and assistants in a Squad.

To create the tool and add it to an assistant, see Set up the Transfer Call tool. If a transfer doesn’t start, connect, or return the caller to the assistant, see Troubleshoot call transfers.

What happens during a transfer

Every transfer follows the same steps until the destination call leg starts:

The model calls the transfer call tool.
If the tool has no stored destination, Vapi sends a transfer-destination-request to your server and waits for the response. Nothing plays to the caller while Vapi waits, so a slow response is silence on the call.
The assistant says one transfer message. See Configure transfer messages.
Vapi sends a status-update message with status set to forwarding. This message is sent before the transfer is attempted, so you receive it even when the transfer fails.
The transfer starts. The transfer mode decides what the caller and destination hear next.

For every mode except assistant-based warm transfer, the original assistant leaves the call when the transfer starts and the call ends with assistant-forwarded-call.

Choose a transfer mode

The transfer mode controls what happens on the destination call leg before the caller is connected. The Dashboard displays a readable label; API requests use the corresponding transferPlan.mode value.

Dashboard mode	API value	What it does
Blind transfer	`blind-transfer`	Connects the caller without speaking to the destination. This is the default. See Blind transfer.
Blind transfer with summary in SIP header	`blind-transfer-add-summary-to-sip-header`	Adds a generated summary to the `X-Transfer-Summary` SIP header, then transfers immediately. Vapi numbers and bring-your-own SIP trunks only. Other providers transfer without the header. See Blind transfer.
Warm transfer with message	`warm-transfer-say-message`	Speaks a fixed message to the destination before connecting the caller. Twilio only. Other providers transfer without the message. See Warm transfer.
Warm transfer with summary	`warm-transfer-say-summary`	Speaks a generated conversation summary to the destination before connecting. Twilio only. Other providers transfer without the summary. See Warm transfer.
Warm transfer with TwiML	`warm-transfer-twiml`	Executes TwiML on the destination call leg before connecting. Twilio only. Other providers transfer without the TwiML. See Warm transfer.
Warm transfer - wait for operator, then say message	`warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`	Waits for destination speech, then delivers a fixed message. Twilio only. Other providers transfer without the message. See Warm transfer.
Warm transfer - wait for operator, then say summary	`warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`	Waits for destination speech, then delivers a generated summary. Twilio only. Other providers transfer without the summary. See Warm transfer.
Warm transfer - experimental	`warm-transfer-experimental`	Places the caller on hold and supports fallback, summaries, custom audio, or a transfer-assistant conversation. Works on Twilio (phone-number destinations), Vapi numbers, and bring-your-own SIP trunks. See Assistant-based warm transfer.

Use Dynamic call transfers when the destination is selected at runtime. Dynamic destination selection is separate from the transfer mode.

What the destination receives

A phone or SIP destination receives the call audio and, depending on the mode and phone provider, an introduction. It doesn’t receive the transcript, variables, or assistant context. To move a conversation to another assistant with its context, use the handoff tool.

Caller ID

Set callerId on a destination to choose the number the destination sees. It accepts an E.164 number, {{customer.number}} for the caller’s number, or {{phoneNumber.number}} for the phone number that received the call. Without callerId, the default depends on the phone provider:

Phone provider	Default caller ID
Twilio	The caller’s number. If the caller’s number is withheld, the phone number that received the call.
Vapi numbers	The Vapi number that received the call
Bring-your-own SIP trunk	With `sipVerb` set to `dial`, the phone number that received the call. With `refer`, your SIP provider sets the caller ID and `callerId` doesn’t apply.
Telnyx	Telnyx sets the caller ID. Telnyx ignores `callerId`.
Vonage	The phone number that received the call. Vonage ignores `callerId`.

Assistant-based warm transfer presents the caller’s number where the phone provider allows it. On Twilio, it presents the caller’s number only when Twilio verified the incoming call. Otherwise, it presents the phone number that received the call.

Introductions and headers

Spoken introduction: Twilio warm transfer modes speak a message or summary to the destination before the caller joins. Twilio speaks it, so it doesn’t use the assistant’s voice. See Warm transfer.
Summary header: On Vapi numbers and bring-your-own SIP trunks, blind-transfer-add-summary-to-sip-header sends a generated summary in the X-Transfer-Summary SIP header. It’s never spoken.
Custom SIP headers: On Vapi numbers, bring-your-own SIP trunks, and Telnyx, sipHeaders on the destination are sent with the transfer. Twilio doesn’t send custom SIP headers.

You can include variables in a destination’s message, summary prompt, and sipHeaders to pass caller details.

Summaries

Vapi generates summaries from the conversation transcript using transferPlan.summaryPlan. Who hears the summary depends on the mode:

Mode	Summary is delivered to
`warm-transfer-say-summary`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`	The destination, spoken by Twilio
`blind-transfer-add-summary-to-sip-header`	The destination’s SIP system, in the `X-Transfer-Summary` header
`warm-transfer-experimental`	The operator, as the transfer assistant’s first message, when `transferPlan.summaryPlan.enabled` is `true`

Understand transfer outcomes and fallback

The assistant-forwarded-call ended reason means Vapi initiated a transfer or delegated call control to your server. By itself, it does not confirm that the destination answered or that the caller and destination spoke. Check the provider’s call record to confirm the downstream result.

Transfer mode	Caller state before connection	If the transfer fails
`blind-transfer`	The transfer starts without an operator introduction.	Doesn’t wait for an answer. On Twilio, Telnyx, and Vonage, a busy or unanswered call ends. On Vapi numbers and bring-your-own SIP trunks, the caller can return to the assistant only if `fallbackPlan` is configured.
`blind-transfer-add-summary-to-sip-header`	The transfer starts with a generated summary in the `X-Transfer-Summary` SIP header.	The summary is not spoken. The transfer call tool does not wait for operator acceptance.
`warm-transfer-say-message`	The destination hears a fixed message before the caller is connected.	This mode does not run an assistant that can accept or cancel the transfer.
`warm-transfer-say-summary`	The destination hears a generated summary before the caller is connected.	This mode does not run an assistant that can accept or cancel the transfer.
`warm-transfer-twiml`	The destination call leg executes the configured TwiML before the caller is connected.	The TwiML controls the introduction; this mode does not run a transfer assistant.
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`	The destination speaks before hearing the fixed message.	`transferPlan.timeout` limits the wait for destination speech. It is not a failed-transfer fallback.
`warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`	The destination speaks before hearing the generated summary.	`transferPlan.timeout` limits the wait for destination speech. It is not a failed-transfer fallback.
`warm-transfer-experimental`	The caller waits on hold while the destination call leg runs.	The transfer assistant can connect or cancel. After a failed attempt, the original assistant says the fallback message, then continues or ends the call. See Assistant-based warm transfer.

Find out what happened to a transfer

No server message reports a failed phone or SIP transfer. After the call, check:

endedReason: On Vapi numbers and bring-your-own SIP trunks, a busy destination ends the call with call.forwarding.operator-busy, an unanswered one with call.forwarding.no-answer, and a rejected or failed transfer with call.in-progress.error-transfer-failed. See Call end reasons.
Call logs: Open the call in Calls under Logs, select its Logs tab, and search for transfer. The Transfer Completed entry has a result of connected, busy, no-answer, or unconfirmed.

If Vapi doesn’t receive a final outcome, it reports the transfer as assistant-forwarded-call and the log result is unconfirmed. That doesn’t confirm the destination answered or even received the call. To trace a transfer step by step, see Troubleshoot call transfers.

Return the caller to the assistant after a failed transfer

On Vapi numbers and bring-your-own SIP trunks, add a fallbackPlan to the destination’s transferPlan so a failed blind transfer returns the caller to the assistant. The assistant says fallbackPlan.message, which defaults to Could not transfer the call. Then:

With endCallEnabled set to false, the assistant keeps helping the caller.
With endCallEnabled set to true or not set, the call ends.

In assistant-based warm transfer, the default is the opposite: if endCallEnabled isn’t set, the caller stays with the assistant.

Test the selected mode with the same phone provider and destination used in production. For a transfer that requires an operator to accept the caller, configure assistant-based warm transfer and an explicit fallbackPlan.

Common transfer scenarios

Each scenario pairs a common reason for handing a caller to a person with the destination, transfer mode, and fallback settings that fit it. The scenarios differ in how much control you keep. A blind transfer connects the caller fastest but can’t bring them back if no one answers. Assistant-based warm transfer confirms that a person accepted before connecting the caller. Start from the scenario that matches why the caller needs a person, then check that your phone provider supports the transfer mode it uses.

Need	Configure	Expected result and recovery
Escalate when the caller asks or the assistant reaches a capability boundary	Add a transfer destination and describe the trigger in the tool description and assistant prompt. Require caller agreement when appropriate.	The model must invoke `transferCall`; speech alone does not start a transfer. Use call logs to confirm invocation.
Route to a specialist	Give each stored destination a distinct description, or use a lookup-based transfer.	The selected destination receives the transfer attempt. Confirm the selected route in the tool call and provider record.
Give an operator context before connecting	Use a supported warm transfer mode with a message or summary.	The destination hears the introduction before connection. These modes do not ask an assistant to confirm acceptance.
Require a person to accept a high-stakes escalation	Use assistant-based warm transfer. Prompt the transfer assistant to call `transferSuccessful` only after acceptance and `transferCancel` when it should decline. Set `fallbackPlan.endCallEnabled` explicitly.	The caller waits on hold during the operator conversation. A canceled attempt or handled operator-leg failure follows the configured fallback; test busy, no-answer, and voicemail outcomes with the production provider.