---
title: "从 Amazon Connect 连接"
description: "通过 SIP 将 Amazon Connect 通话连同联系人 ID 和 UUI 发送至 ThunderPhone 智能体，并通过智能体的转接继续您的流程。"
---

您的 Amazon Connect 流程会将来电者连同联系 ID 以及您设置的任何 UUI 一起发送给智能体。智能体完成后会挂断，您的流程将继续执行，而 Lambda 会通过联系 ID 获取转接信息。

## 开始前准备

- 一个 ThunderPhone 智能体和一个组织 [API 密钥](/zh/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/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/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 秒后超时。
