部署电话CCaaS 集成

Five9

使用 Five9 AI Agent Connect 将通话从 Five9 VCC 转接至 ElevenAgents。

在阅读本指南前，建议先查看 SIP 中继 指南，了解 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 账户及用于处理转接通话的一个智能体。
  4. 已导入 ElevenLabs、用作 Five9 转接目标的一个 SIP 中继电话号码。

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

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

ElevenLabs 设置

1

导入转接电话号码

按照 SIP 中继指南导入 Five9 将转接通话至的电话号码。自定义 SIP 标头和 BYE 标头需要使用 SIP 中继电话号码。

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

2

分配智能体

如果由单个智能体处理所有来自 Five9 的通话，请在电话号码控制台中将其直接分配给该电话号码。

如果多个智能体共用一个转接号码，请改为分配路由智能体，并按通过一个号码路由多个智能体操作。

3

配置返回标头

将智能体在对话期间设置的动态变量映射至 Five9 所需的 SIP BYE 标头名称。参阅配置 BYE 标头。

4

进行测试通话

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

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

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

传入的 X- 标头会作为动态变量公开，因此路由智能体可通过 {{sip_agentid}} 使用 X-AgentID。为路由智能体配置智能体转接工具，并为每个预期的 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 智能体，用于通过路由智能体进行路由。

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

保留标头 X-Call-ID 和 X-Caller-ID 分别映射到 system__call_sid 和 system__caller_id 系统动态 变量。 Five9 发送的是未加连字符的 X-CallID 和 X-CallANI，它们会分别规范化为 sip_callid 和 sip_callani。在提示词中引用前，请先在测试通话中确认哪些变量已填充。

ElevenLabs 返回至 Five9 的标头

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

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

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

配置 BYE 标头

BYE 标头会将智能体动态变量的最终值返回给 Five9。使用电话号码 inbound_trunk_config 上的 attributes_to_headers，将每个动态变量名称映射到标头名称。可映射智能体设置的变量以及 system__conversation_id 等系统动态变量：

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",
        }
    ),
)

标头值为对话结束时动态变量的值，包括在通话中通过智能体工具或 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-RouteTypeX-RouteValue 示例说明
SkillTransferbilling_support将通话转接至特定 Five9 技能队列。
PhoneTransfer+18005550199将通话转接至外部电话号码。
Hangup空AI 交互后终止通话。
DispositionOnlyResolved结束通话并记录特定处置结果。

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 系统变量。
  • 确认接收通话的电话号码的 inbound_trunk_config 上已设置 attributes_to_headers。
  • 确认键为动态变量名称，值为标头名称，而非相反。
  • 确保智能体确实在对话期间设置了这些动态变量。未设置的变量不会生成标头值。
  • 确认 Five9 在每个转接通话中都发送 X-AgentID。
  • 检查每个 X-AgentID 值是否在路由智能体上有对应的转接规则。
  • 确认路由智能体的转接规则引用 {{sip_agentid}}。

实用链接