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.

Prerequisites

Before you create the tool, prepare:

• A Vapi assistant that handles phone calls
• A reachable destination phone number in E.164 format, for example, +14155550100, or a valid SIP URI
• A private Vapi API key for the curl method

Configure the transfer call tool

Create a reusable transfer call tool, define its destinations, and add it to an assistant.

Dashboard

curl

1

Create the tool

Open Tools in the Vapi Dashboard, click Create Tool, and select Transfer Call.

2

Describe when to transfer

Under Tool Settings, enter a clear Tool Name and Description. Describe the conditions that should trigger a transfer so the assistant can choose the tool reliably.

For example:

System prompt

Transfer the caller to a billing specialist when they ask about an
invoice, refund, or payment. Only transfer after the caller agrees.

3

Add a destination

Under Destinations, click Add Destination, then select Phone Number or SIP. Enter the destination and a specific description of when the assistant should use it.

For a phone number, use E.164 format, including the + prefix and country code. If you add multiple destinations, give each one a distinct description so the assistant can route the caller correctly.

4

Configure transfer messages

Optionally configure a message for the assistant to say before the transfer. If neither the destination nor the tool defines a message, the assistant says Transferring the call now by default. Set the destination message to an empty string for a silent transfer. A message can be at most 1,000 characters.

Expand Transfer Plan to choose how this destination receives the call. Leave Blind Transfer selected for an immediate transfer, or follow the mode-specific guides below to configure another behavior.

5

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.

6

Add the tool to an assistant

Open Assistants and select the assistant. In the assistant’s Tools section, select Add tool and choose the new transfer call tool. Update the system prompt to state exactly when the assistant should transfer the call.

7

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.

Choose a destination

Use the destination type that matches the system receiving the call.

For a phone-number destination that uses an extension, set extension instead of adding the extension to number. Vapi dials the extension after the destination answers.

A destination’s description tells the assistant when to select it. Keep each description specific to a routing intent, for example, billing, sales, or technical support.

To choose among stored destinations based on an API lookup, follow Transfer calls using API Request and Transfer Call tools. To select or construct a destination at runtime instead of storing it on the tool, follow Dynamic call transfers.

Route to multiple destinations

A single transfer call tool can contain multiple phone-number destinations, SIP destinations, or a mix of both. When the assistant invokes the tool, it uses the conversation and each destination’s description to select one destination; it does not call every destination in the array.

In the Dashboard, click Add Destination for each route. Give every destination a distinct description, then add matching routing rules to the assistant’s system prompt. For example:

- Transfer billing questions to the billing phone number.
- Transfer purchase questions to the sales phone number.
- Transfer technical incidents to the support SIP URI.
- If the caller's intent is unclear, ask which team they need before transferring.

With the API, add one object for each route to destinations. Each object can have its own message and transfer plan. When updating a tool, include every destination that should remain because the new destinations array replaces the existing array.

Choose a transfer mode

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

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

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.

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.

Verify the transfer

Place a test call and ask for the destination described in the tool. Confirm that the call log contains a transferCall tool invocation and that the destination rings or answers.

The assistant-forwarded-call ended reason confirms that Vapi initiated or delegated the transfer. It does not confirm that the downstream telephony provider completed it, so check the provider’s call logs when the destination does not receive the call.

Troubleshooting

For dropped calls, provider diagnostics, and SIP packet checks, follow Troubleshoot call transfers. The call ended reasons reference lists transfer-specific outcomes such as call.in-progress.error-transfer-failed.

API reference

The Create Tool API reference documents the public transfer call fields, destination types, transfer plans, messages, and rejection settings. The Update Assistant API reference documents how to assign reusable tools with model.toolIds.

Related guides