Configure assistant-based warm transfer

Assistant-based warm transfer places the customer on hold while a transfer assistant calls the destination. The transfer assistant can give the operator context, confirm that a person is ready, and then complete or cancel the transfer.

Use this mode when the destination must accept the call or receive context before speaking with the customer. For a direct transfer without an operator conversation, use the Transfer Call tool with its default blind-transfer mode.

GPT-Live assistants cannot use assistant-based warm transfer. GPT-Live supports only blind transfers, and only on Twilio and Vapi SIP calls. See GPT-Live compatibility for the full list of supported and unsupported features.

Prerequisites

Before you configure the transfer, prepare:

A Vapi assistant that handles phone calls on a Twilio number, a Vapi number, or a bring-your-own SIP trunk. On other phone providers, the call is transferred without the transfer assistant.
A destination phone number in E.164 format, for example, +14155550100
A private Vapi API key for the curl method
A publicly accessible MP3 or WAV file if you want custom hold or completion audio

How assistant-based warm transfer works

When the original assistant invokes the transfer call tool:

The customer hears the configured transfer message and is placed on hold.
Vapi calls the destination and starts the transfer assistant.
The transfer assistant speaks with the operator and uses the previous conversation as context by default.
The transfer assistant calls transferSuccessful to connect the parties or transferCancel to return the customer to the original assistant.
With transferAssistant configured, a busy or unanswered destination rolls back to the configured fallback. The transfer assistant can also cancel when an operator declines or it reaches voicemail or an automated system. A transfer that doesn’t finish within transferAssistant.maxDurationSeconds (120 seconds by default) rolls back.

The transferSuccessful and transferCancel tools are always available to the transfer assistant. You can customize them through the API, but you do not need to add them to a basic configuration.

Configure the warm transfer

Create a reusable transfer call tool, configure a phone-number destination, and add the tool to the original assistant.

Dashboard

curl

Create a transfer call tool

In the Vapi Dashboard, open Tools, click Create Tool, and select Transfer Call. Enter a name and a description that state when the assistant should use the tool.

Add a phone-number destination

Under Destinations, click Add Destination, then select Phone Number. Enter the destination in E.164 format and describe when the assistant should select it.

Select assistant-based warm transfer

Expand Transfer Plan. Under Transfer Mode, select Warm Transfer - Experimental.

Configure the operator experience

Enter the Message to Operator. Under Fallback Plan, set the message spoken to the customer when the transfer fails and choose whether to end the call. Under Summary Plan, choose whether to generate a conversation summary for the operator.

Save and add the tool to the assistant

Click Save. Open Assistants, select the original assistant, and add the tool from the assistant’s Tools section. Update the system prompt with the conditions for starting the transfer, then save the assistant.

The Dashboard exposes the transfer mode, operator message, fallback plan, and summary plan. Use the API to configure a custom transfer-assistant model, prompt, timeouts, voice, hold audio, or completion audio.

Configure transfer behavior

Use these fields to control the transfer assistant and the two call legs. See the Create Tool API reference for complete field definitions and configuration options.

Field	Controls	Default or constraint
`transferAssistant.firstMessage`	What the transfer assistant says when the operator answers	If omitted, the assistant waits for the operator and generates a response
`transferAssistant.firstMessageMode`	Whether the transfer assistant speaks first or waits	`assistant-speaks-first`
`transferAssistant.maxDurationSeconds`	Maximum length of the transfer-assistant conversation	120 seconds; allowed range is 10–43,200 seconds
`transferAssistant.silenceTimeoutSeconds`	Silence allowed before the transfer is canceled	30 seconds; allowed range is 5–3,600 seconds
`transferAssistant.model`	Model and instructions used for the operator conversation	Required when you configure `transferAssistant`
`holdAudioUrl`	MP3 or WAV audio played to the customer while on hold	Default hold audio
`transferCompleteAudioUrl`	MP3 or WAV audio played to the destination after the introduction	No custom completion audio
`fallbackPlan`	Customer message and end-call behavior after a failed warm transfer	If omitted, the original assistant says “Could not transfer the call.” and continues the conversation
`summaryPlan`	Operator summary content and generation timeout	Configure with `enabled`, `messages`, and `timeoutSeconds`
`contextEngineeringPlan`	Conversation context provided to the transfer assistant	All previous messages

firstMessageMode also accepts assistant-waits-for-user and assistant-speaks-first-with-model-generated-message. Use the model-generated option when the introduction should adapt to the preceding conversation.

Prompt the transfer assistant

Keep the transfer assistant’s system message focused on the operator conversation. Define when to use each built-in tool:

Call transferSuccessful after a human operator confirms that they will take the call
Call transferCancel when it hears voicemail, an interactive voice response (IVR) system, an automated hold queue, or an operator declining the call
Answer questions about the transfer or give a brief customer summary
Avoid unrelated conversation and complete the decision before maxDurationSeconds

For example:

System prompt

Call transferCancel if the destination plays an IVR message, automated queue announcement, or hold message. Call transferSuccessful only after a live operator responds and accepts the call.

Busy and no-answer call statuses can trigger rollback before the transfer assistant speaks. The transfer assistant receives the previous conversation by default. Set contextEngineeringPlan.type to none when the operator must not receive that context, or use lastNMessages to limit it.

When you configure the transfer through the API, set fallbackPlan.endCallEnabled. With false, the original assistant says the fallback message and continues the conversation. With true, it says the message and ends the call. If omitted, the caller stays on the call with the original assistant.

Keep transferPlan.transferAssistant configured when you depend on no-answer fallback or a transfer timeout. In the Dashboard, turning off Summary generation can remove that configuration and prevent a no-answer event from starting the fallback. Keep Summary generation on or configure transferAssistant through the API, then verify the result with a controlled call.

Verify the warm transfer

Place a test call and trigger the transfer. Confirm that:

The customer hears the transfer message and hold audio.
The destination receives the call and hears the transfer assistant.
Accepting the call connects the customer and operator.
Declining the call or reaching voicemail returns the customer to the original assistant or ends the call according to fallbackPlan.

In Logs → Calls, inspect the original call, any available destination-leg record, transcript, and ended reason. To retrieve call details through the API, see the Get Call API reference. An assistant-forwarded-call ended reason alone does not confirm that the destination answered.

Assistant-based warm transfers to phone or SIP destinations do not send transfer-update, including when the call switches to the transfer assistant and back. A status-update event with status: "forwarding" signals that the transfer started, not that it succeeded. See transfer event behavior for payloads and subscription requirements.

Troubleshooting

Symptom	Likely cause	Resolution
The customer is transferred without an operator conversation	The destination uses a blind or non-assistant warm-transfer mode, the call uses an unsupported phone provider, or a Twilio call is transferring to a SIP address	Set `transferPlan.mode` to `warm-transfer-experimental`, and use a Twilio number, Vapi number, or bring-your-own SIP trunk. On Twilio, use a phone-number destination.
The transfer assistant never speaks	`firstMessage` is omitted or `firstMessageMode` waits for the operator	Set `firstMessage` and use `assistant-speaks-first`, or let the operator speak first.
The transfer assistant talks but never connects the parties	The prompt does not require `transferSuccessful`	Tell the transfer assistant to call `transferSuccessful` immediately after the operator accepts.
Voicemail, an IVR, a hold queue, or a declined transfer connects anyway	The prompt does not define cancellation conditions	Require `transferCancel` for non-human destinations and declined transfers. Busy and no-answer call statuses can trigger rollback before the transfer assistant speaks.
The customer hears summary text instead of the fallback message	The transfer produced unexpected `warm-transfer-experimental` behavior	Record the affected call ID, the message the customer heard, whether `summaryPlan` was enabled, and the `endedReason`, then contact support.
The customer hears the wrong audio	Hold audio was configured as a tool message	Put customer hold audio in `transferPlan.holdAudioUrl`. Use `transferCompleteAudioUrl` for audio played to the destination after the introduction.
The customer cannot continue after a failed transfer	`fallbackPlan.endCallEnabled` is `true`	Set it to `false` so the original assistant remains on the call.
The transfer ends during a long operator interaction	A duration or silence timeout is too short	Increase `maxDurationSeconds` or `silenceTimeoutSeconds` within the supported ranges.

Check the affected call’s Logs tab in Logs → Calls for validation and transfer errors. If Vapi initiated the transfer but the destination never rings, inspect the telephony provider’s call detail records and follow Troubleshoot call transfers.

API reference

The Create Tool API reference documents transfer destinations and transfer-plan fields. This guide shows the additional transfer-assistant configuration used with warm-transfer-experimental.

Transfer Call tool

Create a transfer call tool and configure its destinations.

Warm transfer

Introduce the caller with a message, summary, or TwiML.

Dynamic call transfers

Choose a transfer destination at runtime.

Troubleshoot call transfers

Diagnose failed or incomplete transfers.