---
title: "从 Genesys Cloud 连接"
description: "通过 BYOC Cloud 中继将 Genesys Cloud 通话连同会话 ID 和 UUI 发送至 ThunderPhone 智能体，并通过 UUI 中的交接信息将通话转回。"
---

您的 Architect 流程会通过 BYOC Cloud 中继将来电者发送给智能体，并附带对话 ID 以及您设置的任何 UUI。当来电者需要人工服务时，智能体会发送 SIP `REFER`，Genesys 接回通话，转接 ID 会通过通话的 UUI 到达。

## 开始前准备

- 一个 ThunderPhone 智能体和一个组织 [API 密钥](/zh/guides/api-keys)。
- 启用了 BYOC Cloud 的 Genesys Cloud，以及一个已开启以下设置的外部中继（类型为 BYOC Carrier 或 PBX）
  （[外部中继设置](https://help.genesys.cloud/articles/external-trunk-settings/)）：
  - **对话标头**，以便 Genesys 在 `x-inin-cnv` 中发送其对话 ID。该设置默认关闭。
  - **UUI 透传**，标头类型为 `User-To-User`，编码为 Hex。
  - **接回和转接**，以便 Genesys 接受智能体的 `REFER`。

## 1. 创建 SIP 端点

Genesys 会响应摘要认证质询，因此请使用标准端点：

```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": "Genesys Cloud"}'
```

请立即保存响应中的 `password`；它仅显示一次。在中继中：

| 设置 | 值 |
|---|---|
| SIP 服务器 | `sip.thunderphone.com`，端口 `5061` |
| 协议 | TLS |
| 摘要认证 | 端点的 `username` 和 `password` |
| 编解码器 | PCMU、PCMA 或 G.722 |

将该中继添加到您站点的出站路由中，并确保其号码计划涵盖流程拨打的地址。

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

在您的 Architect 流程中：

1. 您可以选择添加 **设置 UUI 数据** 操作，为智能体提供上下文，例如 `account=12345`。Genesys 建议不超过 128 个字符。
2. 添加 **转接至号码** 操作，并使用端点的 `sip_uri`，例如 `sip:agent-12-jhxmginwjx@sip.thunderphone.com`。

Genesys 会在 `x-inin-cnv` 中发送对话 ID。ThunderPhone 将其存储为通话的 `external_call_id`。UUI 会以解码后的形式传入提示词，即 `{{sip_uui}}`。

Genesys 中的中继自定义标头是静态的，因此请将每通通话的值放入 UUI。Genesys 为自身保留了 `x-inin`、`x-genesys`、`x-pcv` 和 `x-gcv` 标头前缀。

## 3. 接回通话

智能体会通过 `REFER` 转接到 Genesys 上的某个地址，并将转接 ID 作为十六进制 UUI 放在该地址中。添加此转接号码（请参阅[添加转接号码](/zh/guides/contact-centers/overview)
和[转接地址中的标头](/zh/guides/call-transfers)）：

```json
{
  "name": "Genesys support",
  "number": "sip:support@acme.byoc.mypurecloud.com",
  "headers": {"User-to-User": "{{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

请将该地址替换为可路由回应接来电者的队列或流程的地址，并向 Genesys 确认其格式。`REFER` 如下所示：

```
Refer-To: <sip:support@acme.byoc.mypurecloud.com?User-to-User=5A72336D59...%3Bencoding%3Dhex>
```

启用 **接回和转接** 后，Genesys 会从中继接回通话，并将其路由到该地址。Genesys 文档说明传入的 UUI 会进入 `Call.UUIData`；但未说明接回通话是否也是如此，因此请向 Genesys 确认，或通过测试通话确认接收来电者的流程能否在那里找到转接 ID。要获取摘要和意图，请在 Web 服务数据操作集成中使用 **调用数据操作** 调用转接查询：

- 请求：`GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  后接 `Call.UUIData` 中的 ID。
- 凭据：您的 API 密钥，以 `Authorization: Bearer sk_live_…` 形式发送。
- 输出：将 `handoff.summary` 和 `handoff.intent` 映射到流程变量。

请参阅[查询已转接的通话](/api-reference/calls#look-up-a-handed-off-call)。

## 测试

拨打一个可进入该流程的号码，请求智能体转接给某个人员，并确认
Genesys 会将通话转至您设置的地址。在该流程中，确认
`Call.UUIData` 以文本形式保存交接 ID（如果显示十六进制数字，请检查中继的 UUI 编码是否为 Hex）。然后使用 `GET /v1/calls/{call_id}` 打开通话：
`external_call_id` 应为会话 ID。

## 限制

- **Get SIP Headers** 操作仅读取初始 `INVITE`，因此无法读取智能体 `REFER` 中的任何内容。交接仅通过 UUI 到达 Genesys。
- 当通话包含多个 UUI 标头时，Genesys 会丢弃所有 UUI。
- 转接地址最多保留 254 个字符，因此较长的 UUI 会被截断以适应该限制。
  交接 ID 始终可以容纳。
