| title | Assistant-based warm transfer |
|---|---|
| subtitle | Use AI assistants to facilitate call transfers |
| slug | calls/assistant-based-warm-transfer |
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.
In this guide, you'll learn to:
- Configure transfer assistants with custom prompts
- Control how the assistant interacts with operators
- Handle failed transfer scenarios
When using assistant-based warm transfer:
- Customer requests transfer - The original assistant initiates the transfer
- Customer placed on hold - Customer hears hold music while transfer is attempted
- Transfer assistant calls operator - A dedicated assistant is placed on the call to the destination
- Assistant follows your prompts - The transfer assistant has access to the previous conversation context and follows your configured behavior
- Transfer decision - Based on the interaction, the assistant either:
- Completes transfer (
transferSuccessful) - Merges the calls and exits - Cancels transfer (
transferCancel) - Returns the customer to the original assistant
- Completes transfer (
Transfer cancellation occurs when:
maxDurationSecondsis reached- Operator doesn't answer
- Voicemail is detected (based on your prompt configuration)
- Any condition you define in your prompts
The transfer assistant has access to two built-in tools:
You can configure the transfer assistant to perform various tasks before making a decision, such as: - Informing the operator about the customer's needs - Asking the operator specific questions - Following custom business logic you define in the promptsCompletes the transfer by:
- Merging the customer and operator calls
- Removing the transfer assistant from the call
- Connecting the parties directly
Cancels the transfer by:
- Disconnecting from the operator
- Returning the customer to the original assistant
- Optionally playing a fallback message
The transfer assistant can be configured to handle various operator responses:
```json title="Detailed Transfer Configuration" { "type": "transferCall", "function": { "name": "warmTransferWithContext" }, "destinations": [ { "type": "number", "number": "+14155551234", "transferPlan": { "mode": "warm-transfer-experimental", "transferAssistant": { "firstMessage": "Hi, I have a customer on the line who needs help with their recent order. Are you available?", "firstMessageMode": "assistant-waits-for-user", "maxDurationSeconds": 90, "model": { "provider": "openai", "model": "gpt-4o", "messages": [ { "role": "system", "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" } ] } } } } ], "messages": [ { "type": "request-start", "content": "Transferring you to our specialist. Please hold." }, { "type": "request-failed", "content": "I couldn't reach our specialist. Please try again later.", "endCallAfterSpokenEnabled": true } ] } ```Configure different transfer assistants for different departments:
```json title="Department-specific Transfers" { "type": "transferCall", "function": { "name": "departmentTransferAssistant" }, "destinations": [ { "type": "number", "number": "+1234567890", "description": "Sales team transfer line", "transferPlan": { "mode": "warm-transfer-experimental", "transferAssistant": { "firstMessage": "Hey there, I have a potential customer interested in our enterprise plans. Are you available to pick up the call?", "maxDurationSeconds": 60, "model": { "provider": "openai", "model": "gpt-4o", "messages": [ { "role": "system", "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- Only call the tool when you addressed all the operators questions" } ], "tools": [ { "type": "transferSuccessful", // built-in tool "function": { "name": "transferSuccessful", "description": "Confirm the transfer when operator accepts" }, "messages": [ { "type": "request-start", "content": "Great! I'll connect you to the customer now. One moment please." }, { "type": "request-complete", "content": "https://desert-horse-9859.twil.io/assets/call_complete_chime.mp3" } ] }, { "type": "transferCancel", // built-in tool "function": { "name": "transferCancel", "description": "Cancel the transfer if operator declines or is unavailable" }, "messages": [ { "type": "request-complete", "content": "I'll let the customer know about it." } ] }, { "type": "function", // custom tool "function": { "name": "getCustomerInfo", "description": "Get detailed customer information" }, "server": { "url": "https://vapi-webhook-listener-five.vercel.app/customer" } } ] } } } }, { "type": "number", "number": "+0987654321", "description": "Technical Support team transfer line", "transferPlan": { "mode": "warm-transfer-experimental", "transferAssistant": { "firstMessage": "Hey there, I have a customer experiencing issues with API integration. Can you help?", "maxDurationSeconds": 90, "model": { "provider": "openai", "model": "gpt-4o" } } } } ], "messages": [ { "type": "request-start", "content": "I'll transfer you to our team. Please hold for a moment." }, { "type": "request-complete", "content": "https://desert-horse-9859.twil.io/assets/soothing-sound.mp3" // played as hold music on the customer's side of the call }, { "type": "request-failed", "content": "Sorry, none of our account executives are available right now. Our team get back to you later." } ] } ``` **First message**: Keep it brief and state the purpose clearly. **Timeout duration**: Set `maxDurationSeconds` between 60-120 seconds. This limits how long the operator call can last before automatic cancellation. **System prompts**: Configure your prompts to handle voicemail detection, busy signals, and operator unavailability.Configure your transfer assistant to:
- Detect voicemail - Recognize automated messages and call
transferCancel - Verify human presence - Confirm a person answered before proceeding
- Provide context - Explain the customer's situation based on your knowledge
- Handle rejections - Define behavior when operators decline
- Manage timing - Complete interactions before
maxDurationSeconds
Now that you've configured assistant-based warm transfers:
- Call forwarding: Learn about other transfer modes and options
- Assistant configuration: Configure assistant models and prompts
- Custom tools: Add custom tools to your assistants