Transfer to human

Overview

Human transfer allows a Conversational AI agent to transfer the ongoing call to a specified phone number or SIP URI 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 which supports transfers via Twilio and SIP trunk numbers. 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.

Transfer Types

The system supports two types of transfers:

• Conference Transfer: Default behavior that calls the destination and adds the participant to a conference room, then removes the AI agent so only the caller and transferred participant remain.
• SIP REFER Transfer: Uses the SIP REFER protocol to transfer calls directly to the destination. Works with both phone numbers and SIP URIs, but only available when using SIP protocol during the conversation and requires your SIP Trunk to allow transfer via SIP REFER.

Custom LLM integration

Purpose: Seamlessly hand off conversations to human operators when AI assistance is insufficient.

Trigger conditions: The LLM should call this tool when:

• Complex issues requiring human judgment
• User explicitly requests human assistance
• AI reaches limits of capability for the specific request
• Escalation protocols are triggered

Parameters:

• reason (string, optional): The reason for the transfer
• transfer_number (string, required): The phone number to transfer to (must match configured numbers)
• client_message (string, required): Message read to the client while waiting for transfer
• agent_message (string, required): Message for the human operator receiving the call

Function call format:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "transfer_to_number",
5
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
6
  }
7
}

Implementation: Configure transfer phone numbers and conditions. Define messages for both customer and receiving human operator. Works with both Twilio and SIP trunking.

Numbers that can be transferred to

Currently only SIP trunking phone numbers support transferring to external numbers. Twilio phone numbers currently can only transfer to phone numbers hosted on Twilio. If this is needed we recommended using Twilio numbers via Twilio elastic SIP trunking and our SIP trunking support, rather than via the native integration.

Enabling human transfer

Human transfer is configured using the transfer_to_number system tool.

1

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.

2

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.

3

Define transfer rules

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

• Transfer Type: Choose between Conference (default) or SIP REFER transfer methods
• Number Type: Select Phone for regular phone numbers or SIP URI for SIP addresses
• Phone Number/SIP URI: The target destination in the appropriate format:
  • Phone numbers: E.164 format (e.g., +12125551234)
  • SIP URIs: SIP format (e.g., sip:1234567890@example.com)
• 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 destination to transfer.

SIP REFER transfers require SIP protocol during the conversation and your SIP Trunk must allow transfer via SIP REFER. Only SIP REFER supports transferring to a SIP URI.

Ensure destinations are correctly formatted:

• Phone numbers: E.164 format and associated with a properly configured account
• SIP URIs: Valid SIP format (sip:user@domain or sips:user@domain)

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
    PromptAgentInputToolsItem_System,
7
    SystemToolConfigInputParams_TransferToNumber,
8
    PhoneNumberTransfer,
9
)
10
11
# Initialize the client
12
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
13
14
# Define transfer rules
15
transfer_rules = [
16
    PhoneNumberTransfer(
17
        transfer_destination={"type": "phone", "phone_number": "+15551234567"},
18
        condition="When the user asks for billing support.",
19
        transfer_type="conference"
20
    ),
21
    PhoneNumberTransfer(
22
        transfer_destination={"type": "sip_uri", "sip_uri": "sip:support@example.com"},
23
        condition="When the user requests to file a formal complaint.",
24
        transfer_type="sip_refer"
25
    )
26
]
27
28
# Create the transfer tool configuration
29
transfer_tool = PromptAgentInputToolsItem_System(
30
    type="system",
31
    name="transfer_to_human",
32
    description="Transfer the user to a specialized agent based on their request.", # Optional custom description
33
    params=SystemToolConfigInputParams_TransferToNumber(
34
        transfers=transfer_rules
35
    )
36
)
37
38
# Create the agent configuration
39
conversation_config = ConversationalConfig(
40
    agent=AgentConfig(
41
        prompt=PromptAgent(
42
            prompt="You are a helpful assistant.",
43
            first_message="Hi, how can I help you today?",
44
            tools=[transfer_tool],
45
        )
46
    )
47
)
48
49
# Create the agent
50
response = elevenlabs.conversational_ai.agents.create(
51
    conversation_config=conversation_config
52
)
53
54
# Note: When the LLM decides to call this tool, it needs to provide:
55
# - transfer_number: The phone number to transfer to (must match one defined in rules).
56
# - client_message: Message read to the user during transfer.
57
# - agent_message: Message read to the human operator receiving the call.