Configure warm transfer modes

Traditional warm transfer dials the destination, delivers context on the destination call leg, and then connects the customer. Use these modes when the destination needs a fixed message, generated summary, or Twilio Markup Language (TwiML) instructions before receiving the call.

This guide starts with an existing transfer call tool. To create the tool, configure destinations, and add it to an assistant, follow Transfer call tool. For an AI conversation with the destination, use Assistant-based warm transfer.

These five warm-transfer modes are supported on Twilio calls. Vapi uses Twilio while dialing and controlling the separate call to the receiving person, called the destination leg. Test the transfer through the same Twilio phone number and destination you will use in production.

Choose a warm transfer mode

Choose the mode based on what the destination should hear and whether Vapi should wait for the destination to speak.

Dashboard mode	API value	Destination experience
Warm Transfer with Message	`warm-transfer-say-message`	Hears a fixed message before connection
Warm Transfer with Summary	`warm-transfer-say-summary`	Hears a generated conversation summary before connection
Warm Transfer with TwiML	`warm-transfer-twiml`	Receives the configured TwiML instructions before connection
Warm Transfer - Wait for Operator, Then Say Message	`warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`	Speaks first, then hears a fixed message
Warm Transfer - Wait for Operator, Then Say Summary	`warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`	Speaks first, then hears a generated summary

The wait-first modes are useful when the destination has an automated greeting or when you want to avoid speaking over the operator. Their timeout controls how long Vapi waits before delivering the message or summary.

For more information about Warm Transfer - Experimental, including how to configure an AI assistant to speak with the destination before connecting the customer, see Assistant-based warm transfer.

Configure warm transfer

Update the transfer plan on each destination that should use a traditional warm transfer.

Dashboard

curl

Open the transfer destination

In the Vapi Dashboard, open Tools, select the transfer call tool, and expand Destinations. Select the phone-number destination you want to configure.

Select the transfer mode

Expand Transfer Plan. Under Transfer Mode, select one of the five warm-transfer modes covered by this guide.

Transfer Mode menu showing five traditional warm-transfer modes and assistant-based warm transfer — Select a warm-transfer mode in the Dashboard

Configure the destination content

For a message mode, enter the fixed introduction under Message to Operator.

For a summary mode, use Summary Plan to enable summary generation. Configure the system message, the user message containing {{transcript}}, and a summary timeout from 1 to 60 seconds.

For the TwiML mode, enter valid TwiML in TwiML.

Configure wait-first timing

For either wait-first mode, set Wait for Operator Timeout (seconds) from 1 to 600 seconds. The default is 60 seconds.

Save the tool

Click Save, then place a test call using the same telephony provider and destination type you will use in production.

Configure messages and summaries

A message mode speaks the exact value of transferPlan.message. Use it when every call to the destination can use the same introduction.

A summary mode generates destination-specific context with transferPlan.summaryPlan. The user message must include {{transcript}} if the summary should use the conversation. This is separate from the assistant’s end-of-call analysis summary, which runs after the call and is not spoken during transfer.

Keep destination introductions short. The destination is waiting to receive a live caller, so include only the caller’s intent and the information needed to accept the call. A message value can be at most 1,000 characters.

Configure TwiML

Use warm-transfer-twiml when the destination call leg needs instructions beyond a single message. See Twilio’s TwiML for Programmable Voice reference for the XML format and general behavior. The twiml value can contain at most 4,096 characters and supports these verbs in a Vapi transfer:

Say
Play
Gather
Pause
Hangup

The TwiML runs on the destination call leg before the customer is connected. Test menus and Gather behavior with the exact destination system used in production.

Vapi Dashboard showing Warm Transfer with TwiML and an example TwiML message — Configure TwiML for the destination call leg

Verify the warm transfer

Place a test call and trigger the configured destination. Confirm that:

The destination rings before the customer is connected.
The destination hears the configured message, generated summary, or TwiML output.
A wait-first mode allows the operator to speak before delivering the content.
The customer and destination can hear each other after the introduction.

In Logs → Call Logs, inspect the transfer history and destination content. In Logs → API Logs, check for validation, summary-generation, and transfer errors.

Troubleshooting

Symptom	Likely cause	Resolution
The call transfers, but the destination hears no introduction	The call is not using supported Twilio telephony or the selected mode does not match the configured field	Confirm the call’s telephony provider. Use a message mode with `message`, a summary mode with `summaryPlan`, or TwiML mode with `twiml`.
The destination hears no summary	Only the assistant’s end-of-call summary is configured	Enable `transferPlan.summaryPlan` on the destination and include `{{transcript}}` in its user message.
Summary generation times out	`summaryPlan.timeoutSeconds` is too short for the selected model	Increase the timeout within the 1–60 second range and keep the summary prompt concise.
A wait-first transfer pauses too long	The operator or automated system did not produce detectable speech	Reduce `transferPlan.timeout` or use the corresponding non-wait mode.
The message talks over the destination greeting	A non-wait mode starts the introduction immediately	Use the corresponding Wait for Operator mode and set an appropriate timeout.
The API rejects the TwiML	The value is invalid XML, too long, or uses unsupported verbs	Use valid XML under 4,096 characters and limit the instructions to the supported verbs.
The TwiML behaves differently from the test	The destination interactive voice response system handles timing or input differently	Test the same TwiML against the production destination and simplify `Gather`, `Pause`, or audio timing.

If the transfer is initiated but the destination never rings or the call drops, follow Troubleshoot call forwarding drops.

API reference

The Update Tool API reference documents transfer-plan messages, summary plans, timeouts, and TwiML fields.

Transfer call tool

Create a transfer call tool and configure shared behavior.

Blind transfer

Connect the caller immediately or add a SIP summary header.

Assistant-based warm transfer

Let a transfer assistant converse with the destination.

Troubleshoot forwarding drops

Diagnose incomplete transfers and provider routing failures.