> 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.

# Five9

> **Note**
>
> 在阅读本指南前，建议先查看 [SIP 中继 指南](/docs/zh/eleven-agents/phone-numbers/sip-trunking)，了解 ElevenLabs 如何支持 SIP
> 中继和自定义 SIP 标头。

## 概述

本指南介绍如何使用 Five9 AI Agent Connect 将 ElevenAgents 与 Five9 Virtual Contact Center（VCC）集成。Five9 会将实时通话转接到 ElevenLabs 电话号码，ElevenLabs 智能体处理对话后，再将路由或处置数据返回给 Five9，以便 Five9 流程继续执行。

## Five9 集成的工作方式

Five9 AI Agent Connect 通过 SIP 使用外部转接，并通过双向自定义 SIP `X-` 标头交换通话上下文：

1. **呼入转接**：Five9 IVR External Transfer Module 将通话转接到 ElevenLabs 电话号码，并在 INVITE 上以 SIP `X-` 标头发送通话上下文。
2. **对话**：ElevenLabs 接听通话并将其路由到正确的智能体，可选择先经过路由智能体，然后与来电者进行对话。
3. **返回路径**：对话结束后，ElevenLabs 会将路由和处置数据作为 `X-` 标头附加到 SIP BYE。
4. **AI 后路由**：Five9 将返回的标头映射为通话变量，并继续通话流程，例如转接至人工客服、结束通话或记录处置结果。

## 要求

设置 Five9 集成前，请确保具备：

1. 已启用 AI Agent Connect 的有效 Five9 VCC 域。
2. Five9 配置的管理员访问权限，或由 Five9 实施团队进行更改。
3. ElevenLabs 账户及用于处理转接通话的一个[智能体](/docs/zh/eleven-agents/quickstart)。
4. 已导入 ElevenLabs、用作 Five9 转接目标的一个 [SIP 中继电话号码](/docs/zh/eleven-agents/phone-numbers/sip-trunking)。

> **Note**
>
> AI Agent Connect 是 Five9 VCC 的付费附加组件，默认未启用。开始集成前，请联系 Five9
> 客户经理为域启用此功能。

> **Note**
>
> 配置开始前，双方团队应就转接电话号码、每个方向发送的标头名称、
> 路由值和测试计划达成一致。

## ElevenLabs 设置

#### 导入转接电话号码

按照 [SIP 中继指南](/docs/zh/eleven-agents/phone-numbers/sip-trunking)导入 Five9 将转接通话至的电话号码。自定义 SIP 标头和 BYE 标头需要使用 SIP 中继电话号码。

请以带 `+1` 国家代码的 E.164 格式导入号码（例如 `+18005550100`）。Five9 会以此格式发送转接，格式不匹配将导致转接失败。

#### 分配智能体

如果由单个智能体处理所有来自 Five9 的通话，请在[电话号码控制台](https://elevenlabs.io/app/agents/phone-numbers)中将其直接分配给该电话号码。

如果多个智能体共用一个转接号码，请改为分配路由智能体，并按[通过一个号码路由多个智能体](#routing-multiple-agents-through-one-number)操作。

#### 配置返回标头

将智能体在对话期间设置的动态变量映射至 Five9 所需的 SIP BYE 标头名称。参阅[配置 BYE 标头](#configuring-bye-headers)。

#### 进行测试通话

使用 Five9 发起测试通话，并确认传入标头以动态变量形式到达，且 BYE 标头按预期返回。可在对话历史记录的 **Phone Call** 标签页中查看传入标头值。

## 通过一个号码路由多个智能体

要通过单个 Five9 转接号码将通话路由至多个 ElevenLabs 智能体，请为该电话号码分配一个**路由智能体**，并让 Five9 在 `X-AgentID` 等标头中发送目标智能体。

传入的 `X-` 标头会作为[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)公开，因此路由智能体可通过 `{{sip_agentid}}` 使用 `X-AgentID`。为路由智能体配置[智能体转接](/docs/zh/eleven-agents/customization/tools/system-tools/agent-transfer)工具，并为每个预期的 `X-AgentID` 值添加转接规则，将其映射到应接听该通话的智能体。

这样无需为每个智能体单独配置电话号码。

## Five9 发送至 ElevenLabs 的标头

Five9 可在 INVITE 上以 SIP `X-` 标头发送通话元数据。标头名称会移除 `X-` 前缀、转换为小写、将连字符替换为下划线，并添加 `sip_` 前缀以进行规范化。

| 标头                | 动态变量                    | 说明                               |
| ----------------- | ----------------------- | -------------------------------- |
| `X-CallANI`       | `{{sip_callani}}`       | 来电者的电话号码。                        |
| `X-CallDNIS`      | `{{sip_calldnis}}`      | 拨打的电话号码。                         |
| `X-CallID`        | `{{sip_callid}}`        | 唯一的 Five9 通话标识符。                 |
| `X-CallSessionID` | `{{sip_callsessionid}}` | 当前会话的标识符。                        |
| `X-CallCampaign`  | `{{sip_callcampaign}}`  | Five9 营销活动名称。                    |
| `X-AgentID`       | `{{sip_agentid}}`       | 目标 ElevenLabs 智能体，用于通过路由智能体进行路由。 |

在智能体提示词、首条消息和工具中使用这些变量，为对话提供个性化内容。

> **Note**
>
> 保留标头 `X-Call-ID` 和 `X-Caller-ID` 分别映射到 `system__call_sid` 和
> `system__caller_id` [系统动态 变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables)。
> Five9 发送的是未加连字符的 `X-CallID` 和 `X-CallANI`，它们会分别规范化为 `sip_callid` 和
> `sip_callani`。在提示词中引用前，请先在测试通话中确认哪些变量已填充。

## ElevenLabs 返回至 Five9 的标头

ElevenLabs 会在 SIP BYE 上返回路由和报告数据。以下标头名称是 Five9 AI Agent Connect 的推荐约定：

| 标头                 | 说明                               |
| ------------------ | -------------------------------- |
| `X-RouteType`      | Five9 应执行的操作，例如 `SkillTransfer`。 |
| `X-RouteValue`     | 操作的目标，例如 Five9 技能名称。             |
| `X-RouteReason`    | 路由决策的上下文，例如客户意图。                 |
| `X-ConversationId` | ElevenLabs 对话标识符，用于关联日志。         |

可返回 Five9 流程所需的任何其他 `X-` 标头。每个标头值均来自智能体的动态变量，因此智能体必须在对话期间设置这些变量。

## 配置 BYE 标头

BYE 标头会将智能体动态变量的最终值返回给 Five9。使用电话号码 `inbound_trunk_config` 上的 `attributes_to_headers`，将每个动态变量名称映射到标头名称。可映射智能体设置的变量以及 `system__conversation_id` 等[系统动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables)：

**`Python`**

```python title="Python"
import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs, InboundSipTrunkConfigRequestModel

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

elevenlabs.conversational_ai.phone_numbers.update(
    phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj",
    inbound_trunk_config=InboundSipTrunkConfigRequestModel(
        attributes_to_headers={
            "route_type": "X-RouteType",
            "route_value": "X-RouteValue",
            "route_reason": "X-RouteReason",
            "system__conversation_id": "X-ConversationId",
        }
    ),
)
```

**`JavaScript`**

```typescript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  inboundTrunkConfig: {
    attributesToHeaders: {
      route_type: "X-RouteType",
      route_value: "X-RouteValue",
      route_reason: "X-RouteReason",
      system__conversation_id: "X-ConversationId",
    },
  },
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_trunk_config": {
      "attributes_to_headers": {
        "route_type": "X-RouteType",
        "route_value": "X-RouteValue",
        "route_reason": "X-RouteReason",
        "system__conversation_id": "X-ConversationId"
      }
    }
  }'
```

标头值为对话结束时动态变量的值，包括在通话中通过智能体工具或 webhook 覆盖设置的值。若通话结束时智能体将 `route_type` 设为 `SkillTransfer`，并将 `route_value` 设为 `billing_support`，则会生成以下 BYE 标头：

```
X-RouteType: SkillTransfer
X-RouteValue: billing_support
X-RouteReason: Customer needs help with an invoice
X-ConversationId: conv_7401k6a2b8cxyzmn9pq3r5s7t1uv
```

Five9 随后会将来电者路由至 `billing_support` 技能。

## 推荐路由值

请保持 `X-RouteType` 值简单且可预测，以便 Five9 流程可直接据此分支。

| `X-RouteType`     | `X-RouteValue` 示例 | 说明                   |
| ----------------- | ----------------- | -------------------- |
| `SkillTransfer`   | `billing_support` | 将通话转接至特定 Five9 技能队列。 |
| `PhoneTransfer`   | `+18005550199`    | 将通话转接至外部电话号码。        |
| `Hangup`          | 空                 | AI 交互后终止通话。          |
| `DispositionOnly` | `Resolved`        | 结束通话并记录特定处置结果。       |

## Five9 设置

Five9 实施团队通常会：

1. 为 Five9 域启用 AI Agent Connect。
2. 配置 Five9 IVR 转接流程。
3. 将 ElevenLabs 电话号码添加为转接目标。
4. 配置 External Transfer Module。
5. 配置发送至 ElevenLabs 的出站 `X-` 标头。
6. 配置 ElevenLabs 返回的入站 `X-` 标头。
7. 将返回标头映射为 Five9 通话变量。
8. 配置基于这些变量分支的 AI 后路由逻辑。
9. 端到端测试通话。

## 故障排除

#### 转接通话无法连接

* 确认 ElevenLabs 电话号码已作为 SIP 中继号码导入，且已分配智能体。
* 确认 Five9 External Transfer Module 中配置的转接目标与导入号码一致。
* 检查防火墙是否允许配置的传输方式和端口上的 SIP 信令流量，以及 RTP 端口是否未被阻止。

#### 传入标头无法作为动态变量使用

* 确认 Five9 在 INVITE 上发送带 `X-` 前缀的标头。
* 检查规范化后的变量名称。`X-AgentID` 会变为 `{{sip_agentid}}`，而非 `{{X-AgentID}}` 或 `{{agent_id}}`。
* 查看对话历史记录的 **Phone Call** 标签页，了解哪些标头已到达。
* 自定义标头无法覆盖 `system__call_sid` 和 `system__caller_id` 系统变量。

#### BYE 标头缺失或为空

* 确认接收通话的电话号码的 `inbound_trunk_config` 上已设置 `attributes_to_headers`。
* 确认键为动态变量名称，值为标头名称，而非相反。
* 确保智能体确实在对话期间设置了这些动态变量。未设置的变量不会生成标头值。

#### 路由智能体转接到了错误的智能体

* 确认 Five9 在每个转接通话中都发送 `X-AgentID`。
* 检查每个 `X-AgentID` 值是否在路由智能体上有对应的转接规则。
* 确认路由智能体的转接规则引用 `{{sip_agentid}}`。

## 实用链接

* [SIP 中继指南](/docs/zh/eleven-agents/phone-numbers/sip-trunking)
* [SIP 参考文档](/docs/zh/eleven-agents/phone-numbers/sip-reference)
* [智能体转接工具](/docs/zh/eleven-agents/customization/tools/system-tools/agent-transfer)
* [动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)
* [更新电话号码 API 参考文档](/docs/zh/api-reference/phone-numbers/update)