---
title: "Connettiti da Amazon Connect"
description: "Invia le chiamate Amazon Connect a un agente ThunderPhone tramite SIP con l'ID contatto e l'UUI, quindi riprendi il flusso con il passaggio di consegne dell'agente."
---

Il flusso Amazon Connect invia il chiamante all'agente con l'ID contatto e
qualsiasi UUI impostato. Quando l'agente ha terminato, riaggancia, il flusso
prosegue e una Lambda recupera il passaggio tramite ID contatto.

## Prima di iniziare

- Un agente ThunderPhone e una [chiave API](/it/guides/api-keys) dell'organizzazione.
- Il connettore **Trasferimento vocale esterno** di Amazon Connect. Richiedi
  prima l'aumento della quota "External voice transfer connectors per account":
  il menu rimane nascosto finché AWS non lo approva. AWS fattura ogni connettore
  al giorno ([$100 al giorno dal 21 luglio 2025](https://aws.amazon.com/about-aws/whats-new/2025/07/amazon-connect-announces-per-day/))
  più l'utilizzo al minuto.

<Warning>
  L'attuale guida per amministratori di AWS non include più pagine sul
  trasferimento vocale esterno. Prima di basarti su questa funzionalità,
  conferma con AWS che il connettore sia disponibile per la tua istanza e
  Regione.
</Warning>

## 1. Crea l'endpoint SIP

Il connettore non documenta l'autenticazione digest SIP, quindi crea un
endpoint che accetti chiamate in base all'indirizzo sorgente:

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

Recupera da AWS gli intervalli di segnalazione SIP del connettore per la tua
Regione. Ciascuno deve essere un intervallo IPv4 pubblico di `/16` o più
ristretto (IPv6 `/48` o più ristretto). Consulta
[piattaforme che eseguono l'autenticazione tramite IP sorgente](/it/guides/sip-addresses)
per le regole e il rischio di un indirizzo condiviso da tutti i clienti della
piattaforma. Conserva il valore `sip_uri` della risposta, ad esempio
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

## 2. Invia chiamate con contesto

1. Nella console Amazon Connect, apri **Sistemi vocali esterni → Integrazioni
   di trasferimento vocale** e scegli **Crea**.
2. Seleziona il tipo di destinazione (un SBC) e aggiungi una route in uscita con
   host `sip.thunderphone.com`, porta `5061` e protocollo TLS. L'endpoint
   richiede TLS o TCP (porta `5060`) e rifiuta UDP. AWS non documenta quali
   protocolli offra il connettore, quindi conferma con AWS che possa utilizzare
   uno di essi.
3. Nel flusso, aggiungi un blocco **Trasferisci a numero di telefono** con
   **Trasferisci a** impostato su **Sistema vocale esterno**, quindi imposta:
   - **ARN di destinazione:** il connettore.
   - **A utente:** la parte utente dell'`sip_uri` dell'endpoint, ad esempio
     `agent-12-jhxmginwjx`.
   - **UUI** (facoltativo): contesto per l'agente. Connect lo invia con
     codifica esadecimale.
   - **Riprendi il flusso dopo la disconnessione:** Sì, affinché il flusso
     continui quando l'agente riaggancia.

Connect invia l'ID contatto in `X-Amzn-ConnectContactId`. ThunderPhone lo
memorizza come `external_call_id` della chiamata, che consente al flusso di
trovare la chiamata in seguito. L'UUI raggiunge il prompt come `{{sip_uui}}`.
Le integrazioni di terze parti documentano l'header dell'ID contatto; la
documentazione AWS non lo fa, quindi verificalo con la prima chiamata di test.

## 3. Riprendi la chiamata

AWS non documenta alcun modo per consentire a Connect di leggere le intestazioni sul `BYE` o di accettare un
`REFER` dall'agente. L'agente quindi restituisce la chiamata: saluta e
riaggancia, e il flusso riprende dopo il blocco di trasferimento. Aggiungi questo numero di trasferimento (vedi [Aggiungi il numero di trasferimento](/it/guides/contact-centers/overview)):

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

Quindi recupera il passaggio con un blocco **Invoca funzione AWS Lambda** dopo il
trasferimento. Lambda cerca la chiamata tramite l'ID contatto:

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

Il blocco restituisce una mappa piatta, quindi il flusso può diramarsi in base a `intent` o impostare
`summary` come attributo di contatto per la persona che prende la chiamata. Esegui il
blocco in modo sincrono (fino a 8 secondi) e archivia la chiave API crittografata, ad
esempio in AWS Secrets Manager. I campi della risposta sono descritti in
[Cerca una chiamata passata](/api-reference/calls#look-up-a-handed-off-call).

## Provalo

Chiama un numero nella tua istanza Connect che raggiunge il blocco di trasferimento, chiedi
all'agente di una persona e verifica che il flusso riprenda. Quindi apri la chiamata con
`GET /v1/calls/{call_id}`: `sip_headers` dovrebbe elencare
`x-amzn-connectcontactid` e `external_call_id` dovrebbe corrispondere al `ContactId`
ricevuto dalla tua Lambda. Se il trasferimento fallisce con SIP `404`, ThunderPhone non ha
trovato la parte utente dell'endpoint: deve essere presente sia nell'URI della richiesta sia
nell'intestazione `To`.

## Limiti

- AWS non documenta alcun modo per leggere le intestazioni sul `BYE`, incluso
  `X-TP-Handoff-Id`, quindi l'ID contatto è l'unico collegamento alla chiamata.
- AWS non documenta una lunghezza UUI massima per il connettore.
- Un blocco Lambda sincrono va in timeout dopo 8 secondi.
