Skip to content

Commit fbe88f7

Browse files
goosewingoosewin
committed
feat(call-dynamic-transfers): simplify the doc, link to new examples
1 parent 5a86054 commit fbe88f7

File tree

1 file changed

+77
-105
lines changed

1 file changed

+77
-105
lines changed

‎fern/calls/call-dynamic-transfers.mdx‎

Lines changed: 77 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,87 @@
11
---
2-
title: Dynamic Call Transfers
2+
title: Dynamic call transfers
3+
subtitle: Route calls to different destinations based on real-time conversation context and external data.
34
slug: calls/call-dynamic-transfers
5+
description: Learn how Vapi's dynamic call transfers work and explore implementation patterns for intelligent call routing.
46
---
57

6-
## Before you start
8+
## Overview
79

8-
Prerequisites:
9-
- Access to a server or cloud function that can receive requests from Vapi
10+
Dynamic call transfers enable intelligent routing by determining transfer destinations in real-time based on conversation context, customer data, or external system information. Unlike static transfers with predefined destinations, dynamic transfers make routing decisions on-the-fly during the call.
1011

11-
## Overview
12+
**Key capabilities:**
13+
* Real-time destination selection based on conversation analysis
14+
* Integration with CRM systems, databases, and external APIs
15+
* Conditional routing logic for departments, specialists, or geographic regions
16+
* Context-aware transfers with conversation summaries
17+
* Fallback handling for unavailable destinations
1218

13-
Dynamic call transfers let your assistant transfer calls to different destinations (phone numbers, SIP, or other assistants) based on real-time context. This guide shows you how to set up a custom transfer tool, connect it to your assistant, handle transfer requests with your server, and respond with the right destination or error.
19+
## How It Works
1420

15-
<Steps>
16-
<Step title="Create a custom transfer tool">
17-
Create a transfer tool with an empty `destinations` array. This acts as a placeholder so you can define destinations dynamically at runtime.
18-
19-
```bash
20-
curl -X POST https://api.vapi.ai/tool \
21-
-H "Authorization: Bearer insert-private-key-here" \
22-
-H "Content-Type: application/json" \
23-
-d '{
24-
"type": "transferCall",
25-
"destinations": [],
26-
"function": {
27-
"name": "dynamicDestinationTransferCall"
28-
}
29-
}'
30-
```
31-
</Step>
32-
33-
<Step title="Link the tool to your assistant">
34-
After creating the tool, link it to your assistant. This enables the assistant to trigger the tool during calls.
35-
</Step>
36-
37-
<Step title="Configure the server event">
38-
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.
39-
</Step>
40-
41-
<Step title="Set up your server to handle transfer requests">
42-
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.
43-
</Step>
44-
45-
<Step title="Trigger the tool and process requests">
46-
Use a prompt like this to trigger the transfer tool:
47-
48-
```
49-
[TASK]
50-
trigger the dynamicDestinationTransferCall tool
51-
```
52-
53-
When triggered, the assistant sends a `transfer-destination-request` webhook to your server. The webhook includes call details, transcripts, and messages.
54-
55-
**Sample request payload:**
56-
```json
57-
{
58-
"type": "transfer-destination-request",
59-
"artifact": {
60-
"messages": [...],
61-
"transcript": "Hello, how can I help you?",
62-
"messagesOpenAIFormatted": [...]
63-
},
64-
"assistant": { "id": "assistant123" },
65-
"phoneNumber": "+14155552671",
66-
"customer": { "id": "customer456" },
67-
"call": { "id": "call789", "status": "ongoing" }
68-
}
69-
```
70-
</Step>
71-
72-
<Step title="Respond to transfer requests">
73-
Your server should respond with either a valid `destination` or an `error`.
74-
75-
#### Number destination example
76-
```json
77-
{
78-
"destination": {
79-
"type": "number",
80-
"message": "Connecting you to our support line.",
81-
"number": "+14155552671",
82-
"numberE164CheckEnabled": true,
83-
"callerId": "+14155551234",
84-
"extension": "101"
85-
}
86-
}
87-
```
21+
Dynamic transfers operate by leaving the destination unspecified initially, then using webhooks to determine the appropriate destination when needed.
22+
23+
**Transfer flow:**
24+
1. **Trigger** - Voice agent determines a transfer is needed based on conversation
25+
2. **Webhook** - Vapi sends `transfer-destination-request` to your server with call context
26+
3. **Decision** - Your server analyzes context and external data to determine routing
27+
4. **Response** - Server returns destination details and transfer configuration
28+
5. **Transfer** - Vapi executes the transfer to the determined destination
29+
30+
**Available context:** Your webhook receives conversation transcript, extracted variables, customer information, function parameters, and call metadata.
31+
32+
## Implementation Approaches
33+
34+
**Assistant-based implementation** uses transfer-type tools with conditions interpreted by the assistant through system prompts. The assistant determines when and where to route calls based on clearly defined tool purposes and routing logic in the prompt. Best for quick setup and simpler routing scenarios.
35+
36+
**Workflow-based implementation** uses conditional logic based on outputs from any workflow node - tools, API requests, conversation variables, or other data sources. Conditions evaluate node outputs to determine routing paths within visual workflows. Best for complex business logic, structured decision trees, and team-friendly configuration.
37+
38+
<CardGroup cols={2}>
39+
<Card title="Customer Support Escalation" icon="headset" href="/assistants/examples/support-escalation">
40+
<div className='absolute top-4 right-4'>
41+
<Icon icon="arrow-up-right-from-square" />
42+
</div>
43+
**Assistant-based routing**
8844

89-
#### SIP destination example
90-
```json
91-
{
92-
"destination": {
93-
"type": "sip",
94-
"message": "Connecting your call via SIP.",
95-
"sipUri": "sip:[email protected]",
96-
"sipHeaders": {
97-
"X-Custom-Header": "value"
98-
}
99-
}
100-
}
101-
```
45+
Route customers to appropriate support tiers based on conversation analysis and customer data
46+
</Card>
47+
<Card title="Property Management Routing" icon="building" href="/workflows/examples/property-management">
48+
<div className='absolute top-4 right-4'>
49+
<Icon icon="arrow-up-right-from-square" />
50+
</div>
51+
**Workflow-based routing**
10252

103-
#### Error response example
104-
```json
105-
{
106-
"error": "Invalid destination specified."
107-
}
108-
```
109-
Every response must include either a `destination` or an `error` to indicate the outcome of the transfer request.
110-
</Step>
111-
</Steps>
112-
113-
## Conclusion
114-
115-
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.
53+
Direct tenant calls to the right department with automated verification
54+
</Card>
55+
</CardGroup>
56+
57+
## Routing Patterns
58+
59+
### Common Use Cases
60+
61+
* **Customer support routing** - Route based on issue type, customer tier, agent availability, and interaction history. Enterprise customers and critical issues get priority routing to specialized teams.
62+
63+
* **Geographic routing** - Direct calls to regional offices based on customer location and business hours. Automatically handle time zone differences and language preferences.
64+
65+
* **Load balancing** - Distribute calls across available agents to optimize wait times and agent utilization. Route to the least busy qualified agent.
66+
67+
* **Escalation management** - Implement intelligent escalation based on conversation tone, issue complexity, and customer history. Automatically route urgent issues to senior agents.
68+
69+
### Transfer Configuration
70+
71+
1. **Warm transfers** provide context to receiving agents with AI-generated conversation summaries, ensuring smooth handoffs with full context.
72+
73+
2. **Cold transfers** route calls immediately with predefined context messages, useful for simple departmental routing.
74+
75+
3. **Conditional transfers** apply different transfer modes based on routing decisions, such as priority handling for enterprise customers.
76+
77+
4. **Destination types** include phone numbers for human agents, SIP endpoints for VoIP systems, and Vapi assistants for specialized AI agents.
78+
79+
<Warning>
80+
**Security considerations:** Always verify webhook signatures to ensure requests come from Vapi. Never log sensitive customer data, implement proper access controls, and follow privacy regulations like GDPR and CCPA when handling customer information in routing decisions.
81+
</Warning>
82+
83+
## Related Documentation
84+
85+
* **[Call Forwarding](/call-forwarding)** - Static transfer options and transfer plans
86+
* **[Webhooks](/server-url)** - Webhook security and event handling patterns
87+
* **[Custom Tools](/tools/custom-tools)** - Build custom tools for advanced routing logic

0 commit comments

Comments
 (0)