Transfer to human | ElevenLabs Documentation

Overview

Human transfer allows a Conversational AI agent to transfer the ongoing call to a specified phone number when certain conditions are met. This enables agents to hand off complex issues, specific requests, or situations requiring human intervention to a live operator.

This feature utilizes the transfer_to_number system tool and currently supports transfers via Twilio. When triggered, the agent can provide a message to the user while they wait and a separate message summarizing the situation for the human operator receiving the call.

This feature currently requires a configured native Twilio integration for the phone number receiving the transfer.

Enabling human transfer

Human transfer is configured using the transfer_to_number system tool.

Add the transfer tool

Enable human transfer by selecting the transfer_to_number system tool in your agent’s configuration within the Agent tab. Choose “Transfer to Human” when adding a tool.

Add Human Transfer Tool — Select 'Transfer to Human' tool

Configure tool description (optional)

You can provide a custom description to guide the LLM on when to trigger a transfer. If left blank, a default description encompassing the defined transfer rules will be used.

Human Transfer Tool Description — Configure transfer tool description

Define transfer rules

Configure the specific rules for transferring to phone numbers. For each rule, specify:

Phone Number: The target phone number in E.164 format (e.g., +12125551234) to transfer the call to.
Condition: A natural language description of the circumstances under which the transfer should occur (e.g., “User explicitly requests to speak to a human”, “User needs to update sensitive account information”).

The LLM will use these conditions, along with the tool description, to decide when and to which phone number to transfer.

Human Transfer Rules Configuration — Define transfer rules with phone number and condition

Ensure the phone number is correctly formatted (E.164) and associated with a properly configured Twilio account capable of receiving calls.

API Implementation

You can configure the transfer_to_number system tool when creating or updating an agent via the API. The tool allows specifying messages for both the client (user being transferred) and the agent (human operator receiving the call).

1 from elevenlabs import (
2     ConversationalConfig,
3     ElevenLabs,
4     AgentConfig,
5     PromptAgent,
6     PromptAgentToolsItem_System,
7     SystemToolConfigInputParams_TransferToNumber,
8     PhoneNumberTransfer,
9 )
10 
11 # Initialize the client
12 client = ElevenLabs(api_key="YOUR_API_KEY")
13 
14 # Define transfer rules
15 transfer_rules = [
16     PhoneNumberTransfer(phone_number="+15551234567", condition="When the user asks for billing support."),
17     PhoneNumberTransfer(phone_number="+15559876543", condition="When the user requests to file a formal complaint.")
18 ]
19 
20 # Create the transfer tool configuration
21 transfer_tool = PromptAgentToolsItem_System(
22     type="system",
23     name="transfer_to_number",
24     description="Transfer the user to a human operator based on their request.", # Optional custom description
25     params=SystemToolConfigInputParams_TransferToNumber(
26         transfers=transfer_rules
27     )
28 )
29 
30 # Create the agent configuration
31 conversation_config = ConversationalConfig(
32     agent=AgentConfig(
33         prompt=PromptAgent(
34             prompt="You are a helpful assistant.",
35             first_message="Hi, how can I help you today?",
36             tools=[transfer_tool], # Add the tool here
37         )
38     )
39 )
40 
41 # Create the agent
42 response = client.conversational_ai.create_agent(
43     conversation_config=conversation_config
44 )
45 
46 print(response)
47 
48 # Note: When the LLM decides to call this tool, it needs to provide:
49 # - transfer_number: The phone number to transfer to (must match one defined in rules).
50 # - client_message: Message read to the user during transfer.
51 # - agent_message: Message read to the human operator receiving the call.