---
title: "從 Talkdesk 連線"
description: "透過 Connect to Autopilot Voice 將 Talkdesk 通話轉送至 ThunderPhone 智慧體，並使用 UUI 中的交接 ID 將通話轉回。"
---

你的 Talkdesk Studio 流程會將來電者連線至智慧體，並附上互動 ID 和 UUI。當來電者需要真人處理時，智慧體會透過 SIP `REFER` 將通話升級轉接至 Talkdesk，而交接 ID 會寫入 Studio 變數。

## 開始前

- 一個 ThunderPhone 智慧體和一組組織 [API 金鑰](/zh-Hant/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-Hant/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`。除非另行指定，Twilio 的 SIP 會使用 UDP，而此端點會拒絕透過 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 唯一會讀取它的位置。
新增此轉接號碼（請參閱
[新增轉接號碼](/zh-Hant/guides/contact-centers/overview)
和 [轉接地址中的標頭](/zh-Hant/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}`。
