转接至号码 | ElevenLabs Documentation

概述

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

此功能支持通过电话号码转接。触发后，智能体可在用户等待时向其发送消息，并向接听通话的人工客服发送一条概述情况的独立消息。

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

转接规则

转接规则用于说明智能体应在_何时_转接，以及各电话服务商应_如何_执行转接。
每条规则包含一个条件和每个服务商的一项配置。
工具可配置多条转接规则。
通话期间，智能体只能看到当前通话所用服务商对应的规则。
条件：支持动态变量的纯文本，用于描述何时使用此转接方式，例如“来电者咨询账单”。
服务商配置是一个列表，每个服务商最多一项配置。如果规则中没有某个服务商的配置，该规则在此服务商的通话中便不存在。

转接类型

会议转接：默认行为。呼叫目标号码，并将来电者和人工客服加入同一会议室
SIP REFER：使用 SIP REFER 协议将通话直接转接至目标。支持电话号码和 SIP URI，但仅在通话使用 SIP 协议时可用，并且要求 SIP Trunk 允许通过 SIP REFER 转接

转接策略

冷转接：直接转接通话，不向接听通话的人工客服提供情况摘要。
暖转接：转接时向接听通话的人工客服概述情况。

各服务商可用的转接选项

SIP

冷会议转接：(sip_cold_conference_transfer) 接收方将直接加入通话，不播放提示
- 仅支持电话号码
SIP REFER：(sip_cold_refer_transfer) 通过 SIP REFER 将通话转交给目标，不播放提示
- 支持电话号码和 SIP URI
- 自定义 SIP 标头，可使用静态或动态变量
- UUI（用户到用户信息），用于携带 CRM ID 等上下文
- 播放回铃音（默认开启）：转接完成前，来电者会听到铃声。关闭后则会听到静音。

Twilio

冷转接：(twilio_cold_blind_transfer) 接收方将直接加入通话，不播放提示
- 仅支持电话号码
- 拨号后数字：通话接通后发送的 DTMF 音
暖转接：(twilio_warm_conference_transfer) 接收方先听取智能体的摘要，然后接通
- 仅支持电话号码
- 拨号后数字：通话接通后发送的 DTMF 音

Exotel

冷转接：(exotel_warm_transfer) 接收方将直接加入通话，不播放提示
- 仅支持电话号码
暖转接：(twilio_warm_conference_transfer) 接收方先听取智能体的摘要，然后接通
- 仅支持电话号码

其他配置详解

拨号后数字

通话接通后发送的 DTMF 音，例如 w1W234
每个 w 表示暂停 0.5 秒
每个 W 表示暂停 1 秒

自定义 SIP 标头

随转接发送的额外 SIP 标头，使接收系统（PBX、呼叫中心）能获取数据，例如 X-Customer-ID: 12345。

适用范围：仅 SIP trunk、SIP REFER。
限制：
- 每次转接最多 20 个标头。
- 名称：最多 64 个字符，仅限字母、数字和单个连字符

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

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 参考。

启用人工转接

添加转接工具

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

配置工具说明（可选）

可提供自定义说明，指导 LLM 在何时触发转接。如留空，将使用默认说明，其中列出当前通话电话服务商的转接规则。

（仅限旧版配置）切换至按服务商划分的转接规则

除非工具仍在使用旧版转接，否则请跳过此步骤。在人工转接规则中，选择按服务商。按服务商划分的规则可让你配置智能体在使用的每个电话服务商（Twilio、SIP trunk、Exotel）中如何执行转接，并可使用所有新转接选项。

切换后，旧版转接将转换为等效的按服务商划分规则。在编辑规则前，现有通话的行为不会改变。

工具只能使用旧版转接或按服务商划分的规则，不能同时使用。旧版设置会对所有服务商应用一种转接类型，且不会获得新服务商或转接选项。

添加规则及其条件

点击添加规则并填写条件：说明智能体应在何时使用此转接的自然语言描述（例如“用户明确要求与人工客服通话”或“用户需要更新敏感账户信息”）。条件可包含动态变量。

LLM 会结合这些条件和工具说明，决定何时以及转接至何处。当智能体选择了不存在的目标，但只配置了一个目标时，会使用该目标；若配置了多个目标，转接将被拒绝，智能体会获知有效选项。

为每个电话服务商添加配置

在服务商配置下，为智能体可接听通话的每个电话服务商添加一项配置。新规则会包含分配给智能体的电话号码所对应的服务商。点击 + 可添加更多服务商。

每条规则中，每个服务商只能配置一次。

然后设置目标：

目标类型：电话号码或SIP URI。只有 SIP REFER 可以转接至 SIP URI，其他所有转接类型均使用电话号码。
电话号码 / SIP URI：使用相应格式的目标地址，可直接输入或使用动态变量（例如 {{phone_number}}）：
- 电话号码：E.164 格式（例如 +12125551234）
- SIP URI：SIP 格式（例如 sip:1234567890@example.com）

规则仅存在于其已配置服务商的通话中。如果通话使用 SIP trunk 号码，而规则仅有 Twilio 配置，智能体无法在该通话中提供此转接。

SIP REFER 转接要求通话期间使用 SIP 协议，且 SIP Trunk 必须允许通过 SIP REFER 转接。

两条规则不能在同一服务商中指向同一目标，否则智能体无法区分它们。你始终可以修改条件，将两种情况包含在内。

API 实现

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

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
billing_destination = {"type": "phone", "destination": "+15551234567"}
human_destination = {"type": "phone", "destination": "+15559876543"}
# Each rule lists one config per telephony provider. A call only sees the rules
# that have a config for its provider (twilio, sip_trunk or exotel).
transfer_rules = [
    {
        "condition": "When the user asks for billing support.",
        "provider_configs": [
            {
                "type": "twilio",
                "config": {
                    "type": "twilio_warm_conference_transfer",
                    "transfer_destination": billing_destination,
                    # Wait 1s, then dial extension 1234 (Twilio only)
                    "post_dial_digits": {"type": "static", "value": "ww1234"},
                },
            },
            {
                "type": "sip_trunk",
                "config": {
                    "type": "sip_cold_conference_transfer",
                    "transfer_destination": billing_destination,
                },
            },
            {
                "type": "exotel",
                "config": {
                    "type": "exotel_warm_transfer",
                    "transfer_destination": billing_destination,
                },
            },
        ],
    },
    {
        "condition": "When the user asks to speak to a human.",
        "provider_configs": [
            {
                "type": "twilio",
                "config": {
                    # Preserves caller ID, no warm transfer message
                    "type": "twilio_cold_blind_transfer",
                    "transfer_destination": human_destination,
                },
            },
            {
                "type": "exotel",
                "config": {
                    "type": "exotel_cold_blind_transfer",
                    "transfer_destination": human_destination,
                },
            },
        ],
    },
    {
        "condition": "When the user requests to file a formal complaint.",
        "provider_configs": [
            {
                "type": "sip_trunk",
                "config": {
                    "type": "sip_cold_refer_transfer",
                    "transfer_destination": {"type": "sip_uri", "destination": "sip:support@example.com"},
                    "custom_sip_headers": [
                        {"type": "static", "key": "X-Department", "value": "complaints"},
                        {"type": "static", "key": "X-Priority", "value": "high"},
                        # "dynamic" takes the dynamic variable's name, without {{ }}
                        {"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",
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            # Still required, and must be empty when transfer_rules is set
                            "transfers": [],
                            "transfer_rules": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)

API 文档参考

旧版设置

旧版转接文档

转接类型

系统支持 3 种转接类型：

会议转接：默认行为，会呼叫目标号码并将参与者加入会议室，然后移除 AI 智能体，仅保留来电者和被转接的参与者。使用原生 Twilio 集成时，支持向人工接线员播放预热转接消息（agent_message）。
盲转接：直接将通话转接至目标号码，不向人工接线员播放预热转接消息。保留原始来电显示。仅当智能体电话号码通过原生 Twilio 集成导入时可用。
SIP REFER 转接：使用 SIP REFER 协议将通话直接转接至目标号码。适用于电话号码和 SIP URI，但仅在通话期间使用 SIP 协议时可用，并且要求 SIP Trunk 允许通过 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 Trunk 必须允许通过 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 转接中。会议转接不支持自定义标头。

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

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

SIP REFER 转接可携带用户到用户信息（UUI），即通过 Refer-To 标头的 User-to-User 参数传递给接收平台（例如 Talkdesk 或 Genesys Cloud）的小型载荷。UUI 仅会在转接至 SIP URI 目标地址的 SIP REFER 转接中发送；电话号码（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).