---
title: "从 NICE CXone 连接"
description: "通过 Studio 脚本将 NICE CXone 通话发送给 ThunderPhone 智能体，并在 SIP 标头中携带 ContactID；当脚本继续执行时，查询智能体的转接信息。"
---

您的 CXone Studio 脚本通过 SIP 标头向智能体发起呼叫，这些标头携带联系人 ID 和任何其他上下文。智能体完成后会挂断，脚本中的 REST API 操作会获取交接信息。

## 开始前

- 一个 ThunderPhone 智能体和组织 [API 密钥](/zh/guides/api-keys)。
- 一个接受自定义标头的 CXone SIP 中继组。CXone 发送这些标头之前，您的 NICE 客户代表必须启用此设置。

## 1. 创建 SIP 端点

Placecall 通过 CXone 中继组拨打电话号码，而不是 SIP 地址。NICE 未记录其 SIP 凭据，并且另一家 AI 提供商的 CXone 集成使用带 IP 允许列表的 TLS。因此，请使用脚本将拨打的号码作为呼入号码创建 `ip_allowlist` 端点（请参阅[拨打电话号码的平台](/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": "NICE CXone",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["CXONE_SIGNALLING_RANGE_1", "CXONE_SIGNALLING_RANGE_2"],
    "dial_in_numbers": ["+14155550188"]
  }'
```

- `allowed_source_cidrs`：NICE 提供的 CXone 集群 SIP 信令范围。每个范围都必须是 `/16` 或更窄的公网 IPv4 范围（IPv6 则为 `/48` 或更窄）。
- `dial_in_numbers`：Placecall 将拨打的号码，写法应与 CXone 发送的格式一致。它不必是真实电话号码。该号码不能已在 ThunderPhone 中作为电话号码或其他端点使用，否则会返回 `409`。

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

## 2. 发送带上下文的呼叫

在您的 Studio 脚本中，于 **Placecall** 之前：

1. 添加一个 **Sipputheader** 操作，标头设为 `X-Call-ID`，值设为 `ContactID`。CXone 不会发送自己的 call-id 标头；ThunderPhone 会将此标头存储为该通话的 `external_call_id`。
2. 为智能体应了解的每个其他值添加一个 **Sipputheader** 操作，例如将 `X-Skill` 设为 `support`。它会以 `{{sip_x_skill}}` 的形式传递到提示词中。Sipputheader 支持 `User-to-User`、任何 `X-` 标头以及大多数 `P-` 标头；NICE 建议值不超过 256 个字符。

随后，通过会将该号码发送至 `sip.thunderphone.com` 的中继组执行 **Placecall**，并在请求 URI 和 `To` 标头中都包含该号码。该端点支持 TLS（端口 5061）或 TCP（端口 5060），并拒绝 UDP。NICE 未记录该中继的传输方式，因此请确保其不是 UDP。

## 3. 将通话转回

CXone 仅在 `INVITE` 及其最终响应中读取 SIP 标头，因此智能体会将通话转回：它会道别并挂断，然后您的脚本会再次接回来电者。添加以下转接号码（请参阅[添加转接号码](/zh/guides/contact-centers/overview)）：

```json
{"name": "NICE CXone", "action": "return"}
```

NICE 未记录通过 Placecall 发起的通话结束后脚本是否会继续执行。其他 AI 提供商的 CXone 集成会在挂断前通过 CXone 的 Signal API（`POST /interactions/{contactId}/signal`）向脚本发送信号；ThunderPhone 不会调用该接口。请与 NICE 确认您的脚本如何接回来电者，然后使用 **REST API** 操作获取交接信息：

- `GET https://api.thunderphone.com/v1/calls/handoff?external_call_id=`
  后接 `ContactID`。
- 标头 `Authorization: Bearer sk_live_…`。
- 从响应中读取 `handoff.summary` 和 `handoff.intent`，以路由联系人。

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

## 测试

呼叫运行该脚本的号码，向智能体请求转接给某个人，并检查脚本是否继续执行，以及 REST API 操作是否返回转接结果。如果呼叫始终未到达智能体，请检查 CXone 发送的号码、其源地址是否位于 `allowed_source_cidrs` 中，以及呼叫是否通过 TCP 或 TLS 传入。然后使用 `GET /v1/calls/{call_id}` 打开该通话：`sip_headers` 应列出 `x-call-id`，并且 `external_call_id` 应等于 `ContactID`。

## 限制

- CXone 仅在 `INVITE` 及其最终 `2xx` 中发送和读取标头，因此智能体的 `BYE` 中的任何内容都不会到达脚本。
- NICE 未说明是否接受来自智能体的 `REFER`。
- REST API 操作默认在 10 秒后超时（最长不超过 90 秒），并读取最大 32 KB 的响应。
