---
title: "从 Talkdesk 连接"
description: "通过 Connect to Autopilot Voice 将 Talkdesk 通话转接至 ThunderPhone 智能体，并使用 UUI 中的转接 ID 将其升级转回。"
---

您的 Talkdesk Studio 流程会将来电者连同交互 ID 和 UUI 一起发送给智能体。当来电者需要人工服务时，智能体会通过 SIP `REFER` 将通话升级至 Talkdesk，交接 ID 会写入 Studio 变量。

## 开始前准备

- 一个 ThunderPhone 智能体和一个组织的 [API 密钥](/zh/guides/api-keys)。
- Talkdesk **对话编排器**许可证，其中涵盖处于**外部语音流**模式的 Studio **连接到 Autopilot Voice**组件（[Talkdesk 的文章](https://support.talkdesk.com/hc/en-us/articles/48921776047259)）。
  在智能体保持通话期间，Talkdesk 会按分钟计费。

## 1. 创建 SIP 端点

Talkdesk 仅提供 IP 允许列表文档，因此请创建一个按源地址接受通话的端点：

```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": "Talkdesk",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["TALKDESK_SIGNALLING_RANGE_1", "TALKDESK_SIGNALLING_RANGE_2"],
    "srtp": "optional"
  }'
```

Talkdesk 的文章指出其通过 SRTP 发送音频，而 `"srtp": "optional"`
会在 Talkdesk 提供 SRTP 时响应 SRTP。该文章未说明 Talkdesk 是否要求
SRTP；如果 Talkdesk 告知您需要，请将 `srtp` 设置为 `required`，这会拒绝未使用 SRTP 的通话。

请向 Talkdesk 获取其 SIP 信令地址范围。每个范围都必须是 `/16` 或更窄的公共 IPv4
范围（IPv6 为 `/48` 或更窄）。请参阅
[通过源 IP 进行身份验证的平台](/zh/guides/sip-addresses)。
Talkdesk 通过 Twilio 的网络发送 SIP，该网络地址由所有 Twilio 客户共享，
因此端点地址是阻止其他来电者接入的关键：请勿公开它。
保留响应中的 `sip_uri`，例如
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`。

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

在您的 Studio 流程中，以**外部语音流**模式添加**连接到 Autopilot Voice**，并将其目标设置为端点的 `sip_uri`，后附 `;transport=tls`，例如
`sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls`。该端点会拒绝通过 UDP 的通话；除非另行指定，否则 Twilio 的 SIP 使用 UDP。

Talkdesk 会发送：

- `X-Talkdesk-Interaction-Id`，存储为通话的 `external_call_id`；
- `User-to-User`，经过十六进制编码，例如 `business_hours=open`。它会以解码后的形式作为 `{{sip_uui}}` 传入提示词。

该组件的 2.1 版本还可以发送**已定义的标头**。Talkdesk 的偏好设置页面将其描述为通过 WebSocket 发送的 JSON，因此在依赖它们之前，请向 Talkdesk 确认它们是否会作为 SIP 标头到达。

## 3. 接回通话

智能体会通过 `REFER` 将通话升级至 Talkdesk 的升级地址，并将交接 ID 作为该地址中的十六进制 UUI 传递；这是 Talkdesk 唯一会读取该 ID 的位置。添加此转接号码（请参阅
[添加转接号码](/zh/guides/contact-centers/overview)
和[转接地址中的标头](/zh/guides/call-transfers)）：

```json
{
  "name": "Talkdesk escalation",
  "number": "sip:escalation@talkdesk.com",
  "headers": {"User-to-User": "autopilot_result={{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

该地址与 Talkdesk 文章中提供的地址相同。组件 2.1 版本读取 `autopilot_result=`；1.7 版本读取 `escalate_to=`，因此在 1.7 中请使用该键。`REFER` 如下所示：

```
Refer-To: <sip:escalation@talkdesk.com?User-to-User=6175746F70696C6F745F726573756C743D...%3Bencoding%3Dhex>
```

Talkdesk 会将该值存入 Studio 变量。要获取摘要和意图，请在使用连接构建的自定义集成中添加一个**执行操作**步骤：

- 身份验证类型为 **API 密钥**，标头名称为 `Authorization`，值为
  `Bearer sk_live_…`。
- 请求：`GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  后接变量中的 ID。您也可以使用交互 ID 通过 `external_call_id` 查找通话。
- 根据 `handoff.intent` 路由，并向接听通话的人员显示 `handoff.summary`。

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

## 测试

通过 Studio 流程发起通话，请求智能体转接人工，并检查该流程是否继续通过该组件，且其变量中包含交接 ID。然后使用 `GET /v1/calls/{call_id}` 打开通话：
`external_call_id` 应为 Talkdesk 交互 ID。

## 限制

- Talkdesk 最多读取 256 字节的 UUI，且不允许使用 `|` 或 `;` 分隔的值，因此请发送单个值。交接 ID 符合此限制。
- Talkdesk 的 API 无法读取智能体的转录文本。请改用交接查询或
  `GET /v1/calls/{call_id}`。
