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: a phone number in E.164 format, for example +14155550100, or a SIP URI. On Twilio, use a phone number.
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.

What the caller and destination hear

The caller hears the transfer message, then hold audio. Set transferPlan.holdAudioUrl to use your own hold audio.
Vapi calls the destination. The caller stays on hold and doesn’t hear the operator conversation.
When the operator answers, they hear the summary if transferPlan.summaryPlan.enabled is true. Otherwise, they hear the destination’s message. The transfer assistant then talks with them.
If the transfer assistant calls transferSuccessful, transferCompleteAudioUrl plays to the operator if it’s set, and the caller joins the call.

The destination sees the caller’s number where the phone provider allows it. See Caller ID.

If the transfer fails

If the transfer doesn’t complete, the caller returns to the original assistant, which says fallbackPlan.message. The default is Could not transfer the call. If fallbackPlan.endCallEnabled isn’t set, the caller stays on the call with the original assistant.

If the call ends after the fallback message, its endedReason shows why the transfer failed:

What happened	`endedReason`
The destination was busy, didn’t answer, or the call to it failed	`call.forwarding.operator-busy`
The transfer assistant called `transferCancel`	`call.in-progress.error-warm-transfer-assistant-cancelled`
The operator conversation reached `maxDurationSeconds`	`call.in-progress.error-warm-transfer-max-duration`
The operator was silent for `silenceTimeoutSeconds`	`call.in-progress.error-warm-transfer-silence-timeout`

Voicemail isn’t detected automatically when a transfer assistant is configured. Prompt the transfer assistant to call transferCancel when it reaches voicemail. See Prompt the transfer assistant.

Configure the warm transfer

Create a reusable transfer call tool, configure a phone-number or SIP 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 destination

Under Destinations, click Add Destination, then select Phone Number or SIP. Enter the destination and describe when the assistant should select it. For a phone number, use E.164 format. On Twilio, use a phone-number destination.

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, enter the Fallback Message spoken to the caller when the transfer fails, and choose whether to End call if transfer fails. Under Summary Plan, choose whether to generate a conversation summary for the operator.

Publish the tool

Select Publish in the tool header. Review the changes, then select Next. Enter a Version Name and, optionally, a Description. Select Publish to make the tool version current.

Add the tool to the assistant

Open Assistants and select the original assistant. In the assistant’s Tools section, select Add tool and choose the transfer call tool. Update the system prompt with the conditions for starting the transfer.

Publish the assistant

Select Publish in the assistant header. Review the changes, then select Next. Enter a Version Name and, optionally, a Description. Select Publish to make the assistant version current.

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 Calls under Logs, 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

Open the affected call in Calls under Logs, then check its Logs tab 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.

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.

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.