Assistant-based warm transfer
Overview
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
How it works
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:
maxDurationSeconds
is reached- Operator doesn’t answer
- Voicemail is detected (based on your prompt configuration)
- Any condition you define in your prompts
Configuration
The function.name
property identifies your transfer tool. Use this name when instructing your assistant to perform transfers in system prompts.
Transfer assistant properties
The initial message spoken by the transfer assistant when the operator answers
Maximum duration in seconds for the operator call. The transfer is automatically cancelled if this limit is reached.
Assistant configuration including provider, model, and system messages that control the transfer assistant’s behavior
Built-in tools
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 prompts
transferSuccessful
Completes the transfer by:
- Merging the customer and operator calls
- Removing the transfer assistant from the call
- Connecting the parties directly
transferCancel
Cancels the transfer by:
- Disconnecting from the operator
- Returning the customer to the original assistant
- Optionally playing a fallback message
Additional examples
Handling operator interactions
The transfer assistant can be configured to handle various operator responses:
Multiple departments
Configure different transfer assistants for different departments:
Best practices
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.
System prompt configuration
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
Limitations
- Requires
warm-transfer-experimental
mode - Only works with Twilio phone numbers
- Calls are limited by
maxDurationSeconds
to prevent indefinite duration - Built-in tools (
transferSuccessful
,transferCancel
) are predefined and cannot be modified - The transfer assistant has access to the previous conversation context
Next steps
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