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.

Prerequisites

Before you configure the transfer, prepare:

A Vapi assistant that handles phone calls
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.
If the destination is busy, unreachable, or not human, the fallback plan determines what the customer hears and whether the call ends.

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.

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 when the transfer fails	Default fallback behavior when omitted
`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 for voicemail, a busy signal, no answer, or an operator who declines
Answer questions about the transfer or give a brief customer summary
Avoid unrelated conversation and complete the decision before maxDurationSeconds

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.

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 → Call Logs, inspect the original call, destination call leg, transcript, and ended reason. An assistant-forwarded-call ended reason confirms that the transfer was initiated; it does not confirm that the destination answered.

Troubleshooting

Symptom	Likely cause	Resolution
The customer is transferred without an operator conversation	The destination uses a blind or non-assistant warm-transfer mode	Set `transferPlan.mode` to `warm-transfer-experimental`.
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 or a declined transfer connects anyway	The prompt does not define cancellation conditions	Require `transferCancel` for voicemail, busy signals, no answer, and declined transfers.
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 Logs → API Logs 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 forwarding drops.

API reference

The Create Tool API reference documents the public transfer call destination 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 forwarding drops

Diagnose failed or incomplete transfers.