---
title: "Amazon Connect에서 연결"
description: "연락처 ID와 UUI를 포함해 Amazon Connect 통화를 SIP를 통해 ThunderPhone 에이전트로 전송하고, 에이전트의 핸드오프로 플로를 재개합니다."
---

Amazon Connect 플로우는 연락처 ID와 설정한 UUI를 포함해 발신자를 에이전트로 보냅니다. 에이전트가 작업을 마치면 전화를 끊고, 플로우는 계속 진행되며, Lambda가 연락처 ID로 핸드오프를 조회합니다.

## 시작하기 전에

- ThunderPhone 에이전트 및 조직 [API 키](/ko/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 범위이거나 `/48` 이하의 IPv6 범위여야 합니다. 규칙 및 플랫폼의 모든 고객이 공유하는 주소의 위험은 [소스 IP로 인증하는 플랫폼](/ko/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는 이를 16진수로 인코딩하여 전송합니다.
   - **연결 해제 후 플로우 재개:** 예를 선택합니다. 에이전트가 전화를 끊으면 플로우가 계속 진행됩니다.

Connect는 `X-Amzn-ConnectContactId`로 연락처 ID를 전송합니다. ThunderPhone은 이를 통화의 `external_call_id`로 저장하며, 플로우는 이를 통해 나중에 통화를 찾습니다. UUI는 `{{sip_uui}}`로 프롬프트에 전달됩니다. 서드파티 통합 문서에는 연락처 ID 헤더가 설명되어 있지만 AWS 자체 문서에는 없으므로, 첫 테스트 통화에서 확인합니다.

## 3. 통화를 다시 받습니다

AWS는 Connect가 `BYE`의 헤더를 읽거나 에이전트의 `REFER`를 수락하는 방법을 문서화하지 않았습니다. 따라서 에이전트가 통화를 반환합니다. 작별 인사를 하고 전화를 끊으면 전송 블록 이후에 흐름이 재개됩니다. 다음 전송 번호를 추가합니다([전송 번호 추가](/ko/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초), 예를 들어 AWS Secrets Manager에 API 키를 암호화하여 저장합니다. 응답 필드는 [핸드오프된 통화 조회](/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는 `X-TP-Handoff-Id`를 포함하여 `BYE`의 헤더를 읽는 방법을 문서화하지 않았으므로 연락처 ID가 통화로 돌아가는 유일한 연결 정보입니다.
- AWS는 커넥터의 최대 UUI 길이를 문서화하지 않았습니다.
- 동기식 Lambda 블록은 8초 후 시간 초과됩니다.
