---
title: "從 Talkdesk 連接"
description: "使用 Connect to Autopilot Voice，將 Talkdesk 通話轉接至 ThunderPhone 智能體，並透過 UUI 中的 hand-off id 將通話升級轉回。"
---

你的 Talkdesk Studio 流程會將來電者連同互動 ID 和 UUI 傳送至智能體。當來電者需要真人協助時，智能體會透過 SIP
`REFER` 升級至 Talkdesk，而轉接 ID 會儲存至 Studio 變數。

## 開始前準備

- 一個 ThunderPhone 智能體及一個機構 [API 金鑰](/yue/guides/api-keys)。
- Talkdesk **Conversation Orchestrator** 授權，涵蓋 **外部語音串流** 模式中的 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，請將 `srtp` 設為 `required`，以
拒絕未使用 SRTP 的來電。

向 Talkdesk 索取其 SIP 訊號範圍。每個範圍必須是 `/16` 或更精確的公開 IPv4
範圍（IPv6 則為 `/48` 或更精確）。請參閱
[以來源 IP 驗證的平台](/yue/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 唯一會讀取此資訊的位置。新增此轉接號碼（請參閱
[新增轉接號碼](/yue/guides/contact-centers/overview)
及[轉接地址內的標頭](/yue/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 變數。若要取得摘要及意圖，請在以 Connections 建立的自訂整合中新增 **執行動作** 步驟：

- 驗證類型為 **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}`。
