Dynamic Call Transfers

Create a custom transfer tool

Create a transfer tool with an empty destinations array. This acts as a placeholder so you can define destinations dynamically at runtime.

$
curl -X POST https://api.vapi.ai/tool \
>
     -H "Authorization: Bearer insert-private-key-here" \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
  "type": "transferCall",
>
  "destinations": [],
>
  "function": {
>
    "name": "dynamicDestinationTransferCall"
>
  }
>
}'

Link the tool to your assistant

After creating the tool, link it to your assistant. This enables the assistant to trigger the tool during calls.

Configure the server event

In your assistant settings, select the transfer-destination-request server event. This event sends a webhook to your server whenever a transfer is requested, so you can dynamically determine the destination.

Set up your server to handle transfer requests

Update your assistant’s server URL to point to your server. Your server will receive a webhook with call details whenever a transfer is triggered, and should respond with the appropriate destination or an error.

Trigger the tool and process requests

Use a prompt like this to trigger the transfer tool:

[TASK]
trigger the dynamicDestinationTransferCall tool

When triggered, the assistant sends a transfer-destination-request webhook to your server. The webhook includes call details, transcripts, and messages.

Sample request payload:

1
{
2
  "type": "transfer-destination-request",
3
  "artifact": {
4
    "messages": [...],
5
    "transcript": "Hello, how can I help you?",
6
    "messagesOpenAIFormatted": [...]
7
  },
8
  "assistant": { "id": "assistant123" },
9
  "phoneNumber": "+14155552671",
10
  "customer": { "id": "customer456" },
11
  "call": { "id": "call789", "status": "ongoing" }
12
}

Respond to transfer requests

Your server should respond with either a valid destination or an error.

Number destination example

1
{
2
  "destination": {
3
    "type": "number",
4
    "message": "Connecting you to our support line.",
5
    "number": "+14155552671",
6
    "numberE164CheckEnabled": true,
7
    "callerId": "+14155551234",
8
    "extension": "101"
9
  }
10
}

SIP destination example

1
{
2
  "destination": {
3
    "type": "sip",
4
    "message": "Connecting your call via SIP.",
5
    "sipUri": "sip:customer-support@domain.com",
6
    "sipHeaders": {
7
      "X-Custom-Header": "value"
8
    }
9
  }
10
}

Error response example

1
{
2
  "error": "Invalid destination specified."
3
}

Every response must include either a destination or an error to indicate the outcome of the transfer request.