> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.vapi.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server. # Transfer Call tool > Create a transfer call tool in the Vapi Dashboard or API, add it to an assistant, configure destinations, and troubleshoot invocation and routing failures. 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](/squads/handoff) 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 #### Create the tool Open **Tools** in the [Vapi Dashboard](https://dashboard.vapi.ai/tools), click **Create Tool**, and select **Transfer Call**. ![Vapi Dashboard Create Tool menu with Transfer Call under Phone Call Tools](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/vapi.docs.buildwithfern.com/36d6f5f4ba2e75bb487dbdbff8b1441b04f61b4efe01f8a716cac2c331e2fe3e/static/images/tools/transfer-call/create-transfer-call-tool.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20261007%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261007T001010Z&X-Amz-Expires=604800&X-Amz-Signature=d392c9d48faf03679eda6b48b801d198a1f2ae062bdf622a644598ffd65f23fa&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### 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`** ```text title="System prompt" Transfer the caller to a billing specialist when they ask about an invoice, refund, or payment. Only transfer after the caller agrees. ``` #### 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. ![Vapi Dashboard phone-number destination with an E.164 number and customer message](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/vapi.docs.buildwithfern.com/8a197f22d8711c07ff391f5ca1d1c87c624d7866a38680015c6bd2296ffeb57d/static/images/tools/transfer-call/configure-phone-destination.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20261007%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261007T001010Z&X-Amz-Expires=604800&X-Amz-Signature=d69ed3128155d4669df521cdb5787fb97f326c3bb1d1196393f2f61a7391b01d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### 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. ![Vapi Dashboard destination description and Transfer Plan set to Blind Transfer](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/vapi.docs.buildwithfern.com/deaa0d3ea95f892947553efe15bdddf3791a618a26c26324d5e7cea1ff9be4d5/static/images/tools/transfer-call/configure-destination-routing.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20261007%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261007T001010Z&X-Amz-Expires=604800&X-Amz-Signature=625cf9a865184040c8f08060362d5134e2f4c33f63b595585a7fe577bd2a4b1b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### Add the tool to an assistant Open **Assistants**, select the assistant, and add the new tool from the assistant's **Tools** section. Update the system prompt to state exactly when the assistant should transfer the call, then save the assistant. ![Vapi Dashboard assistant Tools tab with the Add tool button](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/vapi.docs.buildwithfern.com/9af6caaa53fb9393e8458e90a314a96ea6c12e6a151afcdeb6a38cea5864faed/static/images/tools/transfer-call/add-tool-to-assistant.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20261007%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261007T001010Z&X-Amz-Expires=604800&X-Amz-Signature=490f532737bed818236963034db45f3f9aa78d9ceb5f16edbe9295710319e43c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### curl #### Create the tool Send a request to the [Create Tool endpoint](/api-reference/tools/create). Replace `YOUR_API_KEY` with a private Vapi API key and `+14155550100` with the phone number that should receive the call. ```bash curl --request POST \ --url https://api.vapi.ai/tool \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "type": "transferCall", "destinations": [ { "type": "number", "number": "+14155550100", "description": "Transfer to billing for invoice, refund, or payment questions" } ] }' ``` The object inside `destinations` sets the transfer target. For a phone number, set `type` to `number` and provide the destination in the `number` field using E.164 format. To transfer to a SIP endpoint instead, replace that destination object with: ```json { "type": "sip", "sipUri": "sip:support@example.com", "description": "Transfer to the support queue for technical issues" } ``` You can add more destination objects to the array. Use each destination's `description` to tell the assistant when to select it. To change the default `Transferring the call now` announcement, add `message` to the destination object. Set `message` to an empty string for a silent transfer. The response contains the reusable tool's `id`; save it as `TOOL_ID` for the next request. #### Add the tool to an assistant Replace `ASSISTANT_ID` and `TOOL_ID`, then update the assistant with the [Update Assistant endpoint](/api-reference/assistants/update). ```bash curl --request PATCH \ --url https://api.vapi.ai/assistant/ASSISTANT_ID \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "model": { "provider": "openai", "model": "gpt-4o", "toolIds": ["EXISTING_TOOL_ID", "TOOL_ID"] } }' ``` The example uses an OpenAI model. Keep the assistant's current model configuration and include any existing tool IDs in the `toolIds` array. Updating the array replaces its current contents. #### Update the assistant prompt In the assistant's system prompt, define when to transfer and require the assistant to invoke the tool in the same response as its spoken acknowledgment. ```text Transfer the caller to billing only when they ask about an invoice, refund, or payment and agree to be transferred. When you decide to transfer, acknowledge the request and invoke the transfer call tool in the same response. ``` ## Choose a destination Use the destination type that matches the system receiving the call. | Destination | Use it for | Required value | | ------------ | -------------------------------------------------------------------------- | ------------------------ | | Phone number | A person, department, or public switched telephone network (PSTN) endpoint | `number` in E.164 format | | SIP | A SIP trunk, private branch exchange (PBX), or other SIP endpoint | `sipUri` | For a phone-number destination that uses an extension, set `extension`. 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](/calls/transfer-calls-with-api-lookup). To select or construct a destination at runtime instead of storing it on the tool, follow [Dynamic call transfers](/calls/call-dynamic-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: **`System prompt`** ```text title="System prompt" - 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. > **Note** > > To move the conversation to another Vapi assistant, use the [handoff tool](/squads/handoff) instead of a phone or SIP transfer. Handoff works between standalone assistants and between assistants in a Squad, and can carry conversation context into the destination assistant. ## 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. | Dashboard mode | API value | What it does | | ------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Blind Transfer** | `blind-transfer` | Connects the customer without speaking to the destination. This is the default. See [Blind transfer](/tools/transfer-call/blind-transfer). | | **Blind Transfer with Summary in SIP Header** | `blind-transfer-add-summary-to-sip-header` | Adds a generated summary to the `X-Transfer-Summary` SIP header, then transfers immediately. See [Blind transfer](/tools/transfer-call/blind-transfer). | | **Warm Transfer with Message** | `warm-transfer-say-message` | Speaks a fixed message to the destination before connecting the customer. See [Warm transfer](/tools/transfer-call/warm-transfer). | | **Warm Transfer with Summary** | `warm-transfer-say-summary` | Speaks a generated conversation summary to the destination before connecting. See [Warm transfer](/tools/transfer-call/warm-transfer). | | **Warm Transfer with TwiML** | `warm-transfer-twiml` | Executes TwiML on the destination call leg before connecting. See [Warm transfer](/tools/transfer-call/warm-transfer). | | **Warm Transfer - Wait for Operator, Then Say Message** | `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message` | Waits for destination speech, then delivers a fixed message. See [Warm transfer](/tools/transfer-call/warm-transfer). | | **Warm Transfer - Wait for Operator, Then Say Summary** | `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` | Waits for destination speech, then delivers a generated summary. See [Warm transfer](/tools/transfer-call/warm-transfer). | | **Warm Transfer - Experimental** | `warm-transfer-experimental` | Places the customer on hold and supports fallback, summaries, custom audio, or a transfer-assistant conversation. See [Assistant-based warm transfer](/calls/assistant-based-warm-transfer). | Use [Dynamic call transfers](/calls/call-dynamic-transfers) when the destination is selected at runtime. Dynamic destination selection is separate from the transfer mode. ## 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 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 | Symptom | Likely cause | Resolution | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The assistant says it will transfer, but the call remains active | The model generated speech without invoking the tool | Require the acknowledgment and tool invocation in the same response. Check the call log for a `transferCall` invocation. | | The assistant selects the wrong destination | Destination descriptions overlap or do not state a clear routing intent | Give every destination a distinct description and add matching routing rules to the system prompt. | | The tool returns a validation or configuration error | The destination is missing or malformed | Confirm that `destinations` is an array and that each item has a valid `type` and required value. Use E.164 format for PSTN phone numbers. | | The call has `assistant-forwarded-call`, but the destination never rings | Vapi initiated the transfer, but the downstream route did not complete it | Check the affected call's **Logs** tab in [**Logs → Calls**](/observability/logs/call-logs) for transfer errors, then check the provider call detail record and transfer compatibility. For SIP calls, inspect the provider's REFER or dial behavior. | | The assistant transfers when it should continue helping | The prompt permits broad invocation | Narrow the prompt conditions. For tools configured through the API, you can also add a [tool rejection plan](/tools/tool-rejection-plan). | | An assistant-to-assistant transfer stalls or behaves like an external call | The transfer call tool is being used for assistant routing | Use the [handoff tool](/squads/handoff) for transfers between standalone assistants or assistants in a Squad. | For dropped calls, provider diagnostics, and SIP packet checks, follow [Troubleshoot call forwarding drops](/phone-calling/in-call-control/transfer-calls/debug-forwarding-drops). The [call ended reasons reference](/calls/call-ended-reason) lists transfer-specific outcomes such as `call.in-progress.error-transfer-failed`. ## API reference The [Create Tool API reference](/api-reference/tools/create) documents the public transfer call fields, destination types, transfer plans, messages, and rejection settings. The [Update Assistant API reference](/api-reference/assistants/update) documents how to assign reusable tools with `model.toolIds`. ## Related guides #### [Blind transfer](/tools/transfer-call/blind-transfer) Connect the caller immediately or add a SIP summary header. #### [Warm transfer](/tools/transfer-call/warm-transfer) Introduce the caller with a message, summary, or TwiML. #### [Dynamic call transfers](/calls/call-dynamic-transfers) Select a transfer destination at runtime. #### [Lookup-based transfers](/calls/transfer-calls-with-api-lookup) Look up a branch, then transfer to a stored phone number. #### [Assistant-based warm transfer](/calls/assistant-based-warm-transfer) Introduce the caller before connecting the parties. #### [Handoff tool](/squads/handoff) Move the conversation to another assistant or Squad. #### [Troubleshoot forwarding drops](/phone-calling/in-call-control/transfer-calls/debug-forwarding-drops) Diagnose provider, SIP, and call-routing failures. #### [SIP trunking](/advanced/sip/sip-trunk) Connect Vapi to a SIP provider or PBX. #### [Server events](/server-url/events) Receive call and transfer lifecycle events.