---
title: "从 Five9 连接"
description: "通过 AI Agent Connect 将 Five9 通话经由 SIP 发送至 ThunderPhone 智能体，并通过您的 IVR 脚本读取的路由标头将通话转回。"
---

您的 Five9 IVR 脚本会将来电者连同 Five9 的通话详细信息一起发送给智能体。智能体完成后，会在 SIP `BYE` 中携带路由标头挂机，脚本会将其读取到通话变量中以路由来电者。

## 开始前

- 一个 ThunderPhone 智能体和一个组织[API 密钥](/zh/guides/api-keys)。
- Five9 的 **AI 智能体连接**附加组件。Five9 将其限制为已认可的 AI 提供商，并由 Five9 的实施团队进行设置：他们会导入提供商的 IVR 脚本模板、创建通话变量，并将脚本的 **第三方转接**模块指向该提供商。ThunderPhone 尚未在 Five9 的认可名单中：在据此规划之前，请咨询您的 Five9 客户团队或 ThunderPhone 支持团队。

## 1. 创建 SIP 端点

Five9 的第三方转接模块拨打的是电话号码，而不是 SIP 地址；其他提供商的 Five9 集成通过源地址而非密码验证 Five9。因此，请创建一个 `ip_allowlist` 端点，并将 Five9 将要拨打的号码设为拨入号码（参阅[拨打电话号码的平台](/zh/guides/sip-addresses)）：

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Five9",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["FIVE9_SIGNALLING_RANGE_1", "FIVE9_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["+14155550188"]
  }'
```

- `allowed_source_cidrs`：来自 Five9 的 Five9 数据中心 SIP 信令范围。每个范围都必须是 `/16` 或更具体的公共 IPv4 范围（IPv6 则为 `/48` 或更具体）。
- `dial_in_numbers`：Five9 脚本将拨打的号码，必须按 Five9 发送该号码的格式填写。它不必是真实电话号码。该号码不能已在 ThunderPhone 中被用作电话号码或其他端点的号码：否则将返回 `409`。

Five9 的地址由其所有客户共享，因此任何拨打该号码的其他 Five9 客户都会接入您的智能体。选择号码时，请使用一个无人会猜到的长号码（最多 15 位），确保 Five9 将其发送到 ThunderPhone 而不是拨出至电话网络，并且不要公开该号码。

## 2. 发送带上下文的通话

请 Five9 的实施团队执行以下操作：

- 从 **第三方转接**模块将通话发送至 `sip:+14155550188@sip.thunderphone.com`，并在请求 URI 和 `To` 标头中都包含该号码。该模块会在标头中携带该号码及提供商的 SIP 域名。
- 通过 TLS（端口 5061）或 TCP（端口 5060）发送。该端点拒绝 UDP，且 Five9 未公布其使用的传输协议，因此请确保不是 UDP。
- 启用 **第三方通话结束后返回**，以便智能体挂机后脚本继续执行（Five9 允许第三方通话最长持续 3,600 秒）。

Five9 的指南列出了它发送的值（`call.ANI`、`call.DNIS`、
`call.call_id`、`call.session_id`、`call.campaign_name` 等），但未列出其
标头名称。其他 AI 提供商的 Five9 集成文档显示，这些值在 SIP 报文中对应
`X-CallANI`、`X-CallDNIS`、`X-CallID`、`X-CallSessionID`、`X-CallCampaign`
和 `X-AgentID`；请在您的首次测试通话中进行检查。每个值都会以变量形式传递至提示词，例如
`{{sip_x_callcampaign}}`。`X-CallID` 会存储为该通话的
`external_call_id`。

## 3. 接回通话

智能体将通话转回：它会道别并挂断，`BYE` 会携带 Five9 脚本读取的
四个标头。添加此转接号码（请参阅
[添加转接号码](/zh/guides/contact-centers/overview)）：

```json
{
  "name": "Five9 agent",
  "action": "return",
  "headers": {
    "X-RouteType": "SkillTransfer",
    "X-RouteValue": "Support",
    "X-RouteReason": "{{handoff_intent}}",
    "X-CustomMetaData": "handoff_id={{handoff_id}}"
  }
}
```

- `X-RouteType` 和 `X-RouteValue` 会告知脚本将呼叫者发送到哪里，此处为 Support 技能。其他提供商为 `X-RouteType` 记录的值包括
  `SkillTransfer`、`PhoneTransfer`、`Hangup` 和 `DispositionOnly`；请与维护脚本的人员确认这些值。对于多个目标，为每个目标添加一个回转，并使用不同的名称和 `X-RouteValue`。
- `X-RouteReason` 携带智能体的意图标签，例如 `billing_dispute`。
- `X-CustomMetaData` 携带转接 ID。`BYE` 还会将其作为
  `X-TP-Handoff-Id` 携带，但 Five9 不会读取它。

Five9 的脚本会将这四个标头映射为通话变量。对于智能体摘要，让脚本通过 IVR **查询**模块调用转接查询：
`GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=` 后接
`call.call_id`，并使用发送
`Authorization: Bearer` 和您的 API 密钥的授权配置文件。请参阅
[查询已转接的通话](/api-reference/calls#look-up-a-handed-off-call)。

## 测试

拨入 IVR 脚本，向智能体请求人工坐席，并检查脚本是否在通话变量已填充的情况下路由呼叫者。如果呼叫始终未到达智能体，请检查请求 URI 和 `To` 标头中的号码是否与接入号码匹配、Five9 的源地址是否位于 `allowed_source_cidrs` 中，以及呼叫是否通过 TCP 或 TLS 接入。然后使用
`GET /v1/calls/{call_id}` 打开通话：`sip_headers` 应列出 `x-callid`，并且
`external_call_id` 应与 Five9 中的 `call.call_id` 匹配。

## 限制

- Five9 的指南记录了 `BYE` 上的路由数据，且未提及接受 `REFER`，因此转回由脚本执行冷转接。
- Five9 读取 `X-RouteType`、`X-RouteValue`、`X-RouteReason` 和
  `X-CustomMetaData`，而非 `User-to-User`。ThunderPhone 发送的每个标头值最长为 256 字节。
- Five9 建议将自定义标头控制在约十个，以避免数据包分片。
