Dynamic Call Transfers

Introduction to Transfer Destinations

Transferring calls dynamically based on context is an essential feature for handling user interactions effectively. This guide walks you through creating a custom transfer tool, linking it to your assistant, and handling transfer requests with detailed examples. Whether the destination is a phone number, SIP, or another assistant, you’ll learn how to configure it seamlessly.

Step 1: Create a Custom Transfer Tool

To get started, create a transfer tool with an empty destinations array:

$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"
>  }
>}'

This tool acts as a placeholder, allowing dynamic destinations to be defined at runtime.

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

Step 3: Configure the Server Event

Select the transfer-destination-request server event in your assistant settings. This event sends a webhook to your server whenever a transfer is requested, giving you the flexibility to dynamically determine the destination.

Step 4: Set Up Your Server

Ensure your server is ready to handle incoming requests. Update the assistant’s server URL to point to your server, which will process transfer requests and respond with the appropriate destination or error.

Step 5: Trigger the Tool and Process Requests

Use the following prompt to trigger the transfer tool:

[TASK]
trigger the dynamicDestinationTransferCall tool

When triggered, the assistant sends a transfer-destination-request webhook to your server. This webhook contains all the necessary call details, such as transcripts and messages, allowing your server to process the request dynamically.

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}

Step 6: Respond to Transfer Requests

Your server should respond with either a valid destination or an error to indicate why the transfer cannot be completed.

Transfer Destination Request Response Payload

Number Destination

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}

Transfers the call to a specific phone number, with options for caller ID and extensions.

SIP Destination

1{
2  "destination": {
3    "type": "sip",
4    "message": "Connecting your call via SIP.",
5    "sipUri": "sip:[email protected]",
6    "sipHeaders": {
7      "X-Custom-Header": "value"
8    }
9  }
10}

Transfers the call to a SIP URI with optional custom headers.

Error Response

If the transfer cannot be completed, respond with an error:

1{
2  "error": "Invalid destination specified."
3}
  • Field: error
  • Description: Provides a clear reason why the transfer failed.

Destination or Error in Response

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

  • Destination: Provides details for transferring the call.
  • Error: Explains why the transfer cannot be completed.

Conclusion

Dynamic call transfers empower your assistant to route calls efficiently based on real-time data. By implementing this flow, you can ensure seamless interactions and provide a better experience for your users.

Built with