转接至号码 | ElevenLabs Documentation

概述

transfer_to_number 系统工具允许 ElevenLabs 智能体在满足特定条件时，将正在进行的通话转接到指定电话号码或 SIP URI。这让智能体能够将复杂问题、特定请求或需要人工介入的情况转交给人工客服。

此功能支持通过 Twilio 和 SIP 中继号码进行转接。触发后，智能体可以在用户等待时向其播放一条消息，并向接听电话的人工客服提供另一条用于概述情况的消息。

transfer_to_number 系统工具仅适用于电话通话，不适用于聊天小部件。

转接类型

系统支持 3 种转接类型：

会议转接：默认行为。呼叫目标号码并将参与者加入会议室，随后移除 AI 智能体，只保留来电者和被转接的参与者。使用原生 Twilio 集成时，支持向人工客服播放预热转接消息（agent_message）。
盲转接：直接将通话转接到目标号码，不向人工客服播放预热转接消息。保留原始来电显示。仅当智能体电话号码通过原生 Twilio 集成导入时可用。
SIP REFER 转接：使用 SIP REFER 协议将通话直接转接到目标号码。支持电话号码和 SIP URI，但仅在通话期间使用 SIP 协议时可用，并且要求 SIP 中继允许通过 SIP REFER 转接。不支持预热转接消息。

预热转接消息（agent_message）仅在智能体电话号码通过原生 Twilio 集成导入时可用。基于 SIP 的转接不支持预热转接消息。

盲转接仅在智能体电话号码通过原生 Twilio 集成导入时可用，并且当前必须通过 UI 中的 JSON 编辑器配置。在转接工具配置中选择“以 JSON 方式编辑”，然后为所需转接规则设置 "transfer_type": "blind"。

用途：当 AI 协助不足时，将对话无缝转接给人工客服。

触发条件：LLM 应在以下情况下调用此工具：

遇到需要人工判断的复杂问题
用户明确请求人工协助
对特定请求，AI 已达到能力上限
触发升级处理流程

参数：

reason（字符串，选填）：转接原因
transfer_number（字符串，必填）：要转接至的电话号码（必须与已配置号码一致）
client_message（字符串，必填）：等待转接时向客户播报的消息
agent_message（字符串，必填）：发送给接听通话的人工客服的消息

函数调用格式：

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "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.\"}"
  }
}

实现：配置转接电话号码和条件，并分别定义给客户和接听通话的人工客服的消息。支持 Twilio 和 SIP 中继。

可转接的号码

人工转接支持使用 SIP 中继和 Twilio 电话号码转接至外部电话号码。

启用人工转接

通过 transfer_to_number 系统工具配置人工转接。

添加转接工具

在 Agent 标签页的智能体配置中选择 transfer_to_number 系统工具，即可启用人工转接。添加工具时请选择“转接给人工”。

配置工具说明（可选）

可以提供自定义说明，指导 LLM 何时触发转接。如果留空，将使用涵盖已定义转接规则的默认说明。

定义转接规则

配置转接至电话号码或 SIP URI 的具体规则。每条规则请指定：

转接类型：选择会议转接（默认）、盲转接或 SIP REFER 转接
号码类型：普通电话号码请选择“电话”，SIP 地址请选择“SIP URI”
电话号码/SIP URI：采用相应格式的目标地址：
- 电话号码：E.164 格式（例如 +12125551234）
- SIP URI：SIP 格式（例如 sip:1234567890@example.com）
条件：说明应在何种情况下进行转接的自然语言描述（例如“用户明确要求与人工客服交谈”“用户需要更新敏感账户信息”）。

LLM 会结合这些条件和工具说明，决定何时及转接到哪个目标地址。

SIP REFER 转接要求通话期间使用 SIP 协议，且 SIP 中继必须允许通过 SIP REFER 转接。只有 SIP REFER 支持转接至 SIP URI。

盲转接仅在智能体电话号码通过原生 Twilio 集成导入时可用，并且必须通过 JSON 编辑器配置。系统会保留原始来电显示，但不会向人工客服发送预热转接消息。

确保目标地址格式正确：

电话号码：采用 E.164 格式，并关联已正确配置的账户
SIP URI：有效的 SIP 格式（sip:user@domain 或 sips:user@domain）

配置自定义 SIP REFER 标头（可选）

使用 SIP REFER 转接时，可以加入自定义 SIP 标头，向接收系统传递额外信息。

请为每个自定义标头指定：

标头名称：SIP 标头名称（例如 X-Customer-ID、X-Priority）
标头值：标头值，可以是静态文本，也可以包含动态变量

自定义 SIP REFER 标头仅会随 SIP REFER 转接发送。会议转接不支持自定义标头。

ElevenLabs 会自动添加系统标头 X-Conversation-ID 和 X-Caller-ID，并覆盖任何同名的自定义标头（不区分大小写）。

配置用户间信息（UUI）（可选）

SIP REFER 转接可携带用户间信息（UUI）。这是一小段有效负载，会通过 Refer-To 标头的 User-to-User 参数发送至接收平台（例如 Talkdesk 或 Genesys Cloud）。只有转接至 SIP URI 的 SIP REFER 转接会发送 UUI；电话号码（tel:）目标地址不会携带 UUI。

使用 uui 对象为每条转接规则配置 UUI：

data：要发送的纯文本有效负载。ElevenLabs 会对其进行十六进制编码并附加 ;encoding=hex。可以是静态文本，也可以包含动态变量。替换动态变量后最大为 256 字节（UTF-8）；对于纯 ASCII 即为 256 个字符，多字节字符则更少。
protocol_discriminator：单个十六进制八位字节，例如 04。对于会剥离有效负载第一个八位字节的平台，请包含此项；对于原样传递有效负载的平台，请省略此项。
protocol_discriminator_mode：prefix（默认）会在前面加上该八位字节，生成 04<hex>;encoding=hex。pd_parameter 会将其作为单独参数添加，生成 <hex>;pd=04;encoding=hex。

Talkdesk 会原样传递该值，因此请省略协议识别码。除非存在识别码，否则 Genesys Cloud 会剥离有效负载的第一个八位字节，因此请包含 protocol_discriminator。参阅 Genesys UUI 数据格式。

256 字节限制在替换动态变量后生效。请传递账户 ID 等标识符或短代码，不要传递完整通话摘要等自由文本，因为它会超出限制并在转接时被丢弃。

接收入站 SIP 呼叫中的 UUI 无需配置。当传入的 INVITE 包含 User-to-User 标头时，其值会以 {{sip_uui_raw}} 和 {{sip_uui_data}} 动态变量提供给智能体。参阅 SIP 参考。

配置拨号后按键（可选）

拨号后按键是电话接通转接目标后发送的 DTMF 音。可用于自动输入分机号或浏览 IVR（交互式语音应答）菜单。

可以为每条转接规则指定包含以下内容的 post_dial_digits 字符串：

数字（0-9）：标准 DTMF 音
w：延迟 0.5 秒
W：延迟 1 秒
* 和 #：特殊 DTMF 音

例如，ww1234 会在通话接通后等待 1 秒，再拨打分机号 1234。

拨号后按键仅在智能体电话号码（发起转接的号码）通过原生 Twilio 集成导入时可用。目标号码可以是任意电话号码。

只有会议和盲转接类型支持拨号后按键。SIP REFER 转接不支持拨号后按键。

API 实现

通过 API 创建或更新智能体时，可以配置 transfer_to_number 系统工具（创建智能体、更新智能体）。该工具支持分别为客户（被转接的用户）和智能体（接听电话的人工客服）指定消息。

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules
transfer_rules = [
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15551234567"},
        "condition": "When the user asks for billing support.",
        "transfer_type": "conference",
        # Wait 1s, then dial extension 1234 (native Twilio only)
        "post_dial_digits": {"type": "static", "value": "ww1234"},
    },
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15559876543"},
        "condition": "When the user asks to speak to a human.",
        # Native Twilio integration only, preserves caller ID, no warm transfer message
        "transfer_type": "blind",
    },
    {
        "transfer_destination": {"type": "sip_uri", "sip_uri": "sip:support@example.com"},
        "condition": "When the user requests to file a formal complaint.",
        "transfer_type": "sip_refer",
        "custom_sip_headers": [
            {"type": "static", "key": "X-Department", "value": "complaints"},
            {"type": "static", "key": "X-Priority", "value": "high"},
            # Use "dynamic" to read the value from a dynamic variable
            {"type": "dynamic", "key": "X-Customer-ID", "value": "{{customer_id}}"},
        ],
        "uui": {
            "data": "account_id={{customer_id}}",
            "protocol_discriminator": "04",           # Genesys Cloud; omit for Talkdesk
            "protocol_discriminator_mode": "prefix",  # or "pd_parameter"
        },
    },
]
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_number": {
                        "type": "system",
                        "name": "transfer_to_number",
                        # Optional custom description
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)
# Note: When the LLM decides to call this tool, it needs to provide:
# - transfer_number: The phone number to transfer to (must match one defined in rules).
# - client_message: Message read to the user during transfer.
# - agent_message: Message read to the human operator receiving the call (native Twilio integration only, not used for blind transfers or SIP).