---
title: "Conectar a partir do Amazon Connect"
description: "Envie chamadas do Amazon Connect para um agente ThunderPhone via SIP com o ID do contato e a UUI, e retome seu fluxo com a transferência do agente."
---

Seu fluxo do Amazon Connect envia quem liga ao agente com o ID do contato e
qualquer UUI que você definir. Quando o agente termina, ele encerra a chamada,
seu fluxo continua, e uma Lambda busca a transferência pelo ID do contato.

## Antes de começar

- Um agente do ThunderPhone e uma [chave de API](/pt/guides/api-keys) da organização.
- O conector de **Transferência externa de voz** do Amazon Connect. Primeiro,
  solicite o aumento da cota de "Conectores de transferência externa de voz por
  conta": o menu permanece oculto até a AWS aprová-la. A AWS cobra cada conector
  por dia ([$100 por dia desde 21 de julho de 2025](https://aws.amazon.com/about-aws/whats-new/2025/07/amazon-connect-announces-per-day/))
  mais o uso por minuto.

<Warning>
  O guia de administração atual da AWS não tem mais páginas sobre transferência
  externa de voz. Antes de criar algo com esse recurso, confirme com a AWS se o
  conector está disponível para sua instância e Região.
</Warning>

## 1. Crie o endpoint SIP

O conector não documenta a autenticação SIP digest, então crie um endpoint que
aceite chamadas por endereço de origem:

```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"]
  }'
```

Obtenha com a AWS as faixas de sinalização SIP do conector para sua Região. Cada
uma deve ser uma faixa IPv4 pública de `/16` ou mais específica (IPv6 `/48` ou
mais específica). Consulte
[Plataformas que autenticam por IP de origem](/pt/guides/sip-addresses)
para ver as regras e o risco de um endereço compartilhado por todos os clientes
da plataforma. Guarde o `sip_uri` da resposta, por exemplo,
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

## 2. Envie chamadas com contexto

1. No console do Amazon Connect, abra **Sistemas de voz externos → Integrações
   de transferência de voz** e escolha **Criar**.
2. Escolha o tipo de destino (um SBC) e adicione uma rota de saída com host
   `sip.thunderphone.com`, porta `5061` e protocolo TLS. O endpoint exige
   TLS ou TCP (porta `5060`) e recusa UDP. A AWS não documenta quais protocolos
   o conector oferece, então confirme com a AWS que ele pode usar um deles.
3. No seu fluxo, adicione um bloco **Transferir para número de telefone** com
   **Transferir para** definido como **Sistema de voz externo** e configure:
   - **ARN de destino:** o conector.
   - **Para usuário:** a parte de usuário do `sip_uri` do endpoint, como
     `agent-12-jhxmginwjx`.
   - **UUI** (opcional): contexto para o agente. O Connect o envia codificado
     em hexadecimal.
   - **Retomar fluxo após desconexão:** Sim, para que o fluxo continue quando o
     agente encerrar a chamada.

O Connect envia o ID do contato em `X-Amzn-ConnectContactId`. O ThunderPhone o
armazena como o `external_call_id` da chamada, que é como seu fluxo encontra a
chamada depois. O UUI chega ao prompt como `{{sip_uui}}`. Integrações de
terceiros documentam o cabeçalho de ID do contato; a documentação da própria
AWS não, então verifique-o na sua primeira chamada de teste.

## 3. Receba a chamada de volta

A AWS não documenta uma forma de o Connect ler cabeçalhos no `BYE` ou aceitar um
`REFER` do agente. Portanto, o agente devolve a chamada: ele se despede e
desliga, e seu fluxo é retomado após o bloco de transferência. Adicione este
número de transferência (consulte [Adicionar o número de transferência](/pt/guides/contact-centers/overview)):

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

Em seguida, busque a transferência com um bloco **Invocar função do AWS Lambda** após a
transferência. A Lambda busca a chamada pelo ID do contato:

```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 "",
    }
```

O bloco retorna um mapa simples, para que o fluxo possa criar ramificações com base em `intent` ou definir
`summary` como um atributo de contato para a pessoa que atender a chamada. Execute o
bloco de forma síncrona (até 8 segundos) e armazene a chave de API criptografada,
por exemplo, no AWS Secrets Manager. Os campos da resposta estão em
[Buscar uma chamada transferida](/api-reference/calls#look-up-a-handed-off-call).

## Teste

Ligue para um número na sua instância do Connect que alcance o bloco de transferência, peça ao
agente para falar com uma pessoa e verifique se o fluxo é retomado. Em seguida, abra a chamada com
`GET /v1/calls/{call_id}`: `sip_headers` deve listar
`x-amzn-connectcontactid`, e `external_call_id` deve ser igual ao `ContactId`
que sua Lambda recebe. Se a transferência falhar com SIP `404`, o ThunderPhone não
encontrou a parte de usuário do endpoint: ela deve estar tanto no URI da solicitação quanto no
cabeçalho `To`.

## Limites

- A AWS não documenta uma forma de ler cabeçalhos no `BYE`, incluindo
  `X-TP-Handoff-Id`, portanto o ID do contato é o único vínculo de volta à chamada.
- A AWS não documenta um comprimento máximo de UUI para o conector.
- Um bloco Lambda síncrono expira após 8 segundos.
