> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 转接至号码

## 概述

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

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

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

## 转接类型

系统支持 3 种转接类型：

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

> **Note**
>
> 预热转接消息（`agent_message`）仅在智能体电话号码通过[原生 Twilio 集成](/docs/zh/eleven-agents/phone-numbers/twilio-integration/native-integration)导入时可用。基于 SIP 的
> 转接不支持预热转接消息。

> **Note**
>
> **盲转接**仅在智能体电话号码通过[原生 Twilio 集成](/docs/zh/eleven-agents/phone-numbers/twilio-integration/native-integration)导入时可用，并且
> 当前必须通过 UI 中的 JSON 编辑器配置。在转接工具配置中选择“以 JSON 方式编辑”，然后为所需转接规则设置
> `"transfer_type": "blind"`。

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

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

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

**参数**：

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

**函数调用格式**：

```json
{
  "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 中继](/docs/zh/eleven-agents/phone-numbers/sip-trunking)和 [Twilio 电话号码](/docs/zh/eleven-agents/phone-numbers/twilio-integration/native-integration)转接至外部电话号码。

## 启用人工转接

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

#### 添加转接工具

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

![添加人工转接工具](/docs/_fern-img/1b0a0985dd32cab9532b38b80aaa90873b4076bb26e7a47ce2e12832dd78ea45.webp)

#### 配置工具说明（可选）

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

![人工转接工具说明](/docs/_fern-img/23b446030f915db9a10693153e44f95ab59c313e01df2b95291e40e12f2f4bde.webp)

#### 定义转接规则

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

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

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

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

> **Note**
>
> **盲转接**仅在智能体电话号码通过[原生 Twilio 集成](/docs/zh/eleven-agents/phone-numbers/twilio-integration/native-integration)导入时可用，并且必须通过 JSON 编辑器配置。系统会保留原始来电显示，但不会向人工客服发送预热转接消息。

![人工转接规则配置](/docs/_fern-img/86e46148dc133fe68e6b517752d38bf493bef8347fee91a577e9f27600bafa5d.webp)

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

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

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

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

* **标头名称**：SIP 标头名称（例如 `X-Customer-ID`、`X-Priority`）
* **标头值**：标头值，可以是静态文本，也可以包含[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)

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

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

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

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

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

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

> **Note**
>
> Talkdesk 会原样传递该值，因此请省略协议识别码。除非存在识别码，否则 Genesys Cloud 会剥离有效负载的第一个八位字节，因此请包含 `protocol_discriminator`。参阅 [Genesys UUI 数据格式](https://help.genesys.cloud/articles/uui-data-formats/)。

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

接收入站 SIP 呼叫中的 UUI 无需配置。当传入的 INVITE 包含 `User-to-User` 标头时，其值会以 `{{sip_uui_raw}}` 和 `{{sip_uui_data}}` 动态变量提供给智能体。参阅 [SIP 参考](/docs/zh/eleven-agents/phone-numbers/sip-reference)。

#### 配置拨号后按键（可选）

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

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

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

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

> **Note**
>
> **拨号后按键**仅在智能体电话号码（发起转接的号码）通过[原生 Twilio 集成](/docs/zh/eleven-agents/phone-numbers/twilio-integration/native-integration)导入时可用。目标号码可以是任意电话号码。

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

## API 实现

通过 API 创建或更新智能体时，可以配置 `transfer_to_number` 系统工具（[创建智能体](/docs/zh/api-reference/agents/create)、[更新智能体](/docs/zh/api-reference/agents/update)）。该工具支持分别为客户（被转接的用户）和智能体（接听电话的人工客服）指定消息。

```python
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).
```

```javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY",
});

await elevenlabs.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hi, how can I help you today?",
      prompt: {
        prompt: "You are a helpful assistant.",
        builtInTools: {
          transferToNumber: {
            type: "system",
            name: "transfer_to_number",
            description: "Transfer the user to a human operator based on their request.", // Optional custom description
            params: {
              systemToolType: "transfer_to_number",
              transfers: [
                {
                  transferDestination: { type: "phone", phoneNumber: "+15551234567" },
                  condition: "When the user asks for billing support.",
                  transferType: "conference",
                  // Wait 1s, then dial extension 1234 (native Twilio only)
                  postDialDigits: { type: "static", value: "ww1234" },
                },
                {
                  transferDestination: { type: "phone", phoneNumber: "+15559876543" },
                  condition: "When the user asks to speak to a human.",
                  // Native Twilio only, preserves caller ID, no warm transfer message
                  transferType: "blind",
                },
                {
                  transferDestination: { type: "sip_uri", sipUri: "sip:support@example.com" },
                  condition: "When the user requests to file a formal complaint.",
                  transferType: "sip_refer",
                  customSipHeaders: [
                    { 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}}",
                    protocolDiscriminator: "04", // Genesys Cloud; omit for Talkdesk
                    protocolDiscriminatorMode: "prefix", // or "pd_parameter"
                  },
                },
              ],
            },
          },
        },
      },
    },
  },
});

// 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).
```