---
title: "從 Amazon Connect 連線"
description: "透過 SIP 將 Amazon Connect 通話連同聯絡人 ID 和 UUI 傳送至 ThunderPhone 智慧體，並透過智慧體的交接恢復你的流程。"
---

你的 Amazon Connect 流程會將來電者連同聯絡 ID 與你設定的任何 UUI 傳送至智慧體。智慧體完成後會掛斷，你的流程會繼續執行，並由 Lambda 依聯絡 ID 擷取轉接資訊。

## 開始前

- 一個 ThunderPhone 智慧體與組織的 [API 金鑰](/zh-Hant/guides/api-keys)。
- Amazon Connect 的 **外部語音轉接**連接器。請先申請增加「每個帳戶的外部語音轉接連接器」配額：在 AWS 核准前，選單會維持隱藏。AWS 會按日向每個連接器計費（[自 2025 年 7 月 21 日起每日 $100](https://aws.amazon.com/about-aws/whats-new/2025/07/amazon-connect-announces-per-day/)），另加按分鐘計費的使用費。

<Warning>
  AWS 目前的管理指南已不再提供外部語音轉接的頁面。
  在此基礎上建置前，請向 AWS 確認該連接器可用於你的執行個體與區域。
</Warning>

## 1. 建立 SIP 端點

連接器未記載 SIP 摘要驗證，因此請建立一個依來源位址接受來電的端點：

```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": "Amazon Connect",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["CONNECT_SIGNALLING_RANGE_1", "CONNECT_SIGNALLING_RANGE_2"]
  }'
```

請向 AWS 取得你所在區域的連接器 SIP 訊號範圍。每個範圍都必須是 `/16` 或更小的公開 IPv4 範圍（IPv6 則為 `/48` 或更小）。請參閱
[依來源 IP 驗證的平台](/zh-Hant/guides/sip-addresses)
以瞭解規則，以及平台所有客戶共用位址的風險。請保留回應中的 `sip_uri`，例如
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`。

## 2. 傳送附帶情境資訊的通話

1. 在 Amazon Connect 控制台中，開啟 **外部語音系統 → 語音轉接整合**，然後選擇 **建立**。
2. 選擇目的地類型（SBC），並新增一個輸出路由，主機為
   `sip.thunderphone.com`、連接埠為 `5061`、通訊協定為 TLS。端點需要
   TLS 或 TCP（連接埠 `5060`），且會拒絕 UDP。AWS 未記載連接器提供哪些
   通訊協定，因此請向 AWS 確認它能使用其中一種。
3. 在你的流程中，新增 **轉接至電話號碼**區塊，將 **轉接至**設為 **外部語音系統**，並設定：
   - **目的地 ARN**：連接器。
   - **至使用者**：端點 `sip_uri` 的使用者部分，例如
     `agent-12-jhxmginwjx`。
   - **UUI**（選填）：提供給智慧體的情境資訊。Connect 會以十六進位編碼傳送。
   - **中斷連線後繼續流程**：是，讓流程在智慧體掛斷後繼續執行。

Connect 會在 `X-Amzn-ConnectContactId` 中傳送聯絡 ID。ThunderPhone 會將其儲存為通話的 `external_call_id`，讓你的流程稍後能據此找到該通話。UUI 會以 `{{sip_uui}}` 傳送至提示詞。第三方整合文件有記載聯絡 ID 標頭；AWS 自己的文件沒有，因此請在第一次測試通話時確認。

## 3. 取得通話回傳

AWS 並未提供讓 Connect 讀取 `BYE` 標頭或接受來自智慧體 `REFER` 的方法。因此，智慧體會回傳通話：先道別並掛斷，接著你的流程會在轉接區塊後繼續執行。新增此轉接號碼（請參閱[新增轉接號碼](/zh-Hant/guides/contact-centers/overview)）：

```json
{"name": "Amazon Connect", "action": "return"}
```

接著，在轉接後新增 **呼叫 AWS Lambda 函數** 區塊來取得交接資訊。Lambda 會依聯絡人 ID 查詢通話：

```python
import json
import os
import urllib.error
import urllib.parse
import urllib.request


def lambda_handler(event, context):
    contact_id = event["Details"]["ContactData"]["ContactId"]
    url = "https://api.thunderphone.com/v1/calls/handoff?" + urllib.parse.urlencode(
        {"external_call_id": contact_id}
    )
    request = urllib.request.Request(
        url, headers={"Authorization": "Bearer " + os.environ["THUNDERPHONE_API_KEY"]}
    )
    try:
        with urllib.request.urlopen(request, timeout=5) as response:
            call = json.load(response)
    except (urllib.error.URLError, TimeoutError):
        return {"found": "false"}
    handoff = call.get("handoff") or {}
    return {
        "found": "true",
        "intent": handoff.get("intent") or "",
        "summary": handoff.get("summary") or "",
    }
```

此區塊會回傳扁平對應表，因此流程可依 `intent` 分支，或將 `summary` 設為接聽人員的聯絡人屬性。請同步執行區塊（最長 8 秒），並以加密方式儲存 API 金鑰，例如儲存在 AWS Secrets Manager。回應欄位請參閱[查詢已交接的通話](/api-reference/calls#look-up-a-handed-off-call)。

## 測試

撥打 Connect 執行個體中會進入轉接區塊的號碼，請智慧體轉接給某人，並確認流程會繼續執行。接著使用 `GET /v1/calls/{call_id}` 開啟通話：`sip_headers` 應列出 `x-amzn-connectcontactid`，且 `external_call_id` 應等於你的 Lambda 接收到的 `ContactId`。如果轉接因 SIP `404` 失敗，表示 ThunderPhone 找不到端點的使用者部分：該部分必須同時存在於請求 URI 與 `To` 標頭中。

## 限制

- AWS 並未提供讀取 `BYE` 標頭的方法，包括 `X-TP-Handoff-Id`，因此聯絡人 ID 是唯一可連回通話的連結。
- AWS 未說明連接器的 UUI 長度上限。
- 同步 Lambda 區塊會在 8 秒後逾時。
