Skip to content

Commit e2f263b

Browse files
ramsribramsrib
authored
Added assistant based warm transfer docs (#603)
1 parent bf5a0ec commit e2f263b

File tree

3 files changed

+277
-0
lines changed

3 files changed

+277
-0
lines changed

‎fern/call-forwarding.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -465,6 +465,14 @@ Here is a full example of a `transferCall` payload using the experimental warm t
465465

466466
<Note>This example uses `"audio"` for comprehensive machine detection including beep detection. This is the default option if not specified.</Note>
467467

468+
#### 7. Assistant-Based Warm Transfer (Experimental)
469+
470+
For use cases requiring AI-managed transfers, Vapi supports using assistants to handle the transfer process. This allows the assistant to converse with operators and make transfer decisions based on your configuration.
471+
472+
<Card title="Assistant-based warm transfer" icon="robot" href="/calls/assistant-based-warm-transfer">
473+
Configure AI assistants to handle call transfers with operator conversations
474+
</Card>
475+
468476
**Notes:**
469477

470478
- In all warm transfer modes, the `{{transcript}}` variable contains the full transcript of the call and can be used within the `summaryPlan`.

‎fern/calls/assistant-based-warm-transfer.mdx‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
title: Assistant-based warm transfer
3+
subtitle: Use AI assistants to facilitate call transfers
4+
slug: calls/assistant-based-warm-transfer
5+
---
6+
7+
## Overview
8+
9+
Assistant-based warm transfer uses a dedicated AI assistant to handle the transfer process. You control how this assistant behaves through prompts and configuration. The assistant has access to the previous customer conversation and follows your instructions to decide whether to complete or cancel the transfer.
10+
11+
**In this guide, you'll learn to:**
12+
- Configure transfer assistants with custom prompts
13+
- Control how the assistant interacts with operators
14+
- Handle failed transfer scenarios
15+
16+
## How it works
17+
18+
When using assistant-based warm transfer:
19+
20+
1. **Customer requests transfer** - The original assistant initiates the transfer
21+
2. **Customer placed on hold** - Customer hears hold music while transfer is attempted
22+
3. **Transfer assistant calls operator** - A dedicated assistant is placed on the call to the destination
23+
4. **Assistant follows your prompts** - The transfer assistant has access to the previous conversation context and follows your configured behavior
24+
5. **Transfer decision** - Based on the interaction, the assistant either:
25+
- **Completes transfer** (`transferSuccessful`) - Merges the calls and exits
26+
- **Cancels transfer** (`transferCancel`) - Returns the customer to the original assistant
27+
28+
**Transfer cancellation occurs when:**
29+
- `maxDurationSeconds` is reached
30+
- Operator doesn't answer
31+
- Voicemail is detected (based on your prompt configuration)
32+
- Any condition you define in your prompts
33+
34+
## Configuration
35+
36+
<Note>
37+
The `function.name` property identifies your transfer tool. Use this name when instructing your assistant to perform transfers in system prompts.
38+
</Note>
39+
40+
<CodeBlocks>
41+
```json title="Basic Configuration"
42+
{
43+
"type": "transferCall",
44+
"function": {
45+
"name": "warmTransferAssistant"
46+
},
47+
"destinations": [
48+
{
49+
"type": "number",
50+
"number": "+16509606568",
51+
"message": "I am forwarding your call to customer support. Please stay on the line.",
52+
"transferPlan": {
53+
"mode": "warm-transfer-experimental",
54+
"transferAssistant": {
55+
"firstMessage": "Hi, I have a customer waiting. Are you available to take this call?",
56+
"maxDurationSeconds": 120,
57+
"model": {
58+
"provider": "openai",
59+
"model": "gpt-4o",
60+
"messages": [
61+
{
62+
"role": "system",
63+
"content": "You are handling a warm transfer. Check if the operator is available. If yes, call transferSuccessful. If no answer or voicemail detected, call transferCancel."
64+
}
65+
]
66+
}
67+
}
68+
}
69+
}
70+
]
71+
}
72+
```
73+
</CodeBlocks>
74+
75+
### Transfer assistant properties
76+
77+
<ParamField path="transferAssistant.firstMessage" type="string">
78+
The initial message spoken by the transfer assistant when the operator answers
79+
</ParamField>
80+
81+
<ParamField path="transferAssistant.maxDurationSeconds" type="number">
82+
Maximum duration in seconds for the operator call. The transfer is automatically cancelled if this limit is reached.
83+
</ParamField>
84+
85+
<ParamField path="transferAssistant.model" type="object" required>
86+
Assistant configuration including provider, model, and system messages that control the transfer assistant's behavior
87+
</ParamField>
88+
89+
## Built-in tools
90+
91+
The transfer assistant has access to two built-in tools:
92+
93+
<Note>
94+
You can configure the transfer assistant to perform various tasks before making a decision, such as:
95+
- Informing the operator about the customer's needs
96+
- Asking the operator specific questions
97+
- Following custom business logic you define in the prompts
98+
</Note>
99+
100+
### transferSuccessful
101+
102+
Completes the transfer by:
103+
- Merging the customer and operator calls
104+
- Removing the transfer assistant from the call
105+
- Connecting the parties directly
106+
107+
### transferCancel
108+
109+
Cancels the transfer by:
110+
- Disconnecting from the operator
111+
- Returning the customer to the original assistant
112+
- Optionally playing a fallback message
113+
114+
## Additional examples
115+
116+
### Handling operator interactions
117+
118+
The transfer assistant can be configured to handle various operator responses:
119+
120+
<CodeBlocks>
121+
```json title="Detailed Transfer Configuration"
122+
{
123+
"type": "transferCall",
124+
"function": {
125+
"name": "warmTransferWithContext"
126+
},
127+
"destinations": [
128+
{
129+
"type": "number",
130+
"number": "+14155551234",
131+
"message": "Transferring you to our specialist. Please hold.",
132+
"transferPlan": {
133+
"mode": "warm-transfer-experimental",
134+
"transferAssistant": {
135+
"firstMessage": "Hi, I have a customer on the line who needs help with their recent order. Are you available?",
136+
"maxDurationSeconds": 90,
137+
"model": {
138+
"provider": "openai",
139+
"model": "gpt-4o",
140+
"messages": [
141+
{
142+
"role": "system",
143+
"content": "You are a transfer assistant. Your tasks:\n1. Confirm the operator is human and available\n2. Provide brief context about the customer's needs\n3. If they accept, call transferSuccessful\n4. If they decline or you detect voicemail, call transferCancel\n5. Keep the conversation under 30 seconds"
144+
}
145+
]
146+
}
147+
},
148+
"fallbackPlan": {
149+
"message": "I couldn't reach our specialist. Let me help you directly instead.",
150+
"endCallEnabled": false
151+
}
152+
}
153+
}
154+
]
155+
}
156+
```
157+
</CodeBlocks>
158+
159+
### Multiple departments
160+
161+
Configure different transfer assistants for different departments:
162+
163+
<CodeBlocks>
164+
```json title="Department-specific Transfers"
165+
{
166+
"type": "transferCall",
167+
"function": {
168+
"name": "warmTransferAssistant"
169+
},
170+
"destinations": [
171+
{
172+
"type": "number",
173+
"number": "+1234567890",
174+
"description": "Sales Department",
175+
"transferPlan": {
176+
"mode": "warm-transfer-experimental",
177+
"fallbackPlan": {
178+
"message": "Sorry, none of our account executives are available right now. Our team get back to you later"
179+
},
180+
"transferAssistant": {
181+
"firstMessage": "Hey there, I have a potential customer interested in our enterprise plans. Are you available to pick up the call?",
182+
"maxDurationSeconds": 60,
183+
"model": {
184+
"provider": "openai",
185+
"model": "gpt-4o",
186+
"messages": [
187+
{
188+
"role": "system",
189+
"content": "You are a transfer assistant designed to facilitate call transfers between a customer and an operator. Your core responsibility is to talk to the operator and manage the transfer process efficiently. \n\n## Core Responsibility \n - Facilitate the transfer process by using transferSuccessful or transferCancel tools. Engage briefly with the operator as needed and then facilitate the transfer by calling the corresponding transfer tool. \n ## When to Respond\n- Answer questions about the transfer process or provide summaries when specifically asked by the operator\n- Respond to direct questions about the current transfer situation\n\\n ## Transfer Tools\n- Use transferSuccessful when the operator agrees to accept the call\n- Use transferCancel when the transfer cannot be completed\n\n Rule: Only call the tool when you addressed all the operators questions"
190+
}
191+
]
192+
}
193+
}
194+
}
195+
},
196+
{
197+
"type": "number",
198+
"number": "+0987654321",
199+
"description": "Technical Support",
200+
"transferPlan": {
201+
"mode": "warm-transfer-experimental",
202+
"transferAssistant": {
203+
"firstMessage": "Hey there, I have a customer experiencing issues with API integration. Can you help?",
204+
"maxDurationSeconds": 90,
205+
"model": {
206+
"provider": "openai",
207+
"model": "gpt-4o",
208+
"messages": [
209+
{
210+
"role": "system",
211+
"content": "Transfer to tech support. Explain the technical issue the customer is experiencing."
212+
}
213+
]
214+
}
215+
}
216+
}
217+
}
218+
],
219+
"messages": [
220+
{
221+
"type": "request-start",
222+
"content": "I am forwarding your call to enterprise team. Please stay on the line."
223+
}
224+
]
225+
}
226+
```
227+
</CodeBlocks>
228+
229+
## Best practices
230+
231+
<Tip>
232+
**First message**: Keep it brief and state the purpose clearly.
233+
</Tip>
234+
235+
<Note>
236+
**Timeout duration**: Set `maxDurationSeconds` between 60-120 seconds. This limits how long the operator call can last before automatic cancellation.
237+
</Note>
238+
239+
<Warning>
240+
**System prompts**: Configure your prompts to handle voicemail detection, busy signals, and operator unavailability.
241+
</Warning>
242+
243+
### System prompt configuration
244+
245+
Configure your transfer assistant to:
246+
- **Detect voicemail** - Recognize automated messages and call `transferCancel`
247+
- **Verify human presence** - Confirm a person answered before proceeding
248+
- **Provide context** - Explain the customer's situation based on your knowledge
249+
- **Handle rejections** - Define behavior when operators decline
250+
- **Manage timing** - Complete interactions before `maxDurationSeconds`
251+
252+
## Limitations
253+
254+
<Info>
255+
- Requires `warm-transfer-experimental` mode
256+
- Only works with Twilio phone numbers
257+
- Calls are limited by `maxDurationSeconds` to prevent indefinite duration
258+
- Built-in tools (`transferSuccessful`, `transferCancel`) are predefined and cannot be modified
259+
- The transfer assistant has access to the previous conversation context
260+
</Info>
261+
262+
## Next steps
263+
264+
Now that you've configured assistant-based warm transfers:
265+
- **[Call forwarding](mdc:docs/call-forwarding):** Learn about other transfer modes and options
266+
- **[Assistant configuration](mdc:docs/assistants):** Configure assistant models and prompts
267+
- **[Custom tools](mdc:docs/tools/custom-tools):** Add custom tools to your assistants

‎fern/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -357,6 +357,8 @@ navigation:
357357
contents:
358358
- page: Call forwarding
359359
path: call-forwarding.mdx
360+
- page: Assistant-based warm transfer
361+
path: calls/assistant-based-warm-transfer.mdx
360362
- page: Dynamic call transfers
361363
path: calls/call-dynamic-transfers.mdx
362364
- page: On-hold specialist transfer

0 commit comments

Comments
 (0)