---
title: "Connettiti da Twilio"
description: "Invia le chiamate Twilio a un agente ThunderPhone tramite SIP con il CallSid e riprendile tramite il tuo referUrl con il passaggio di consegne nell'indirizzo di trasferimento."
---

Il tuo TwiML compone l'indirizzo SIP dell'agente con il `CallSid` della chiamata in un'intestazione.
Quando il chiamante ha bisogno di una persona, l'agente invia un `REFER` SIP, Twilio passa l'indirizzo di trasferimento con i dettagli del passaggio al gestore `referUrl` e il TwiML restituito dal gestore decide dove viene indirizzato il chiamante, ad esempio a una coda Flex.

## Prima di iniziare

- Un agente ThunderPhone e una [chiave API](/it/guides/api-keys) dell'organizzazione.
- Twilio Programmable Voice e un ambiente in cui ospitare TwiML e un gestore
  `referUrl`: il tuo server oppure un TwiML Bin e una Twilio Function. Flex è
  facoltativo.

## 1. Crea l'endpoint SIP

Il tag `<Sip>` di Twilio accetta un nome utente e una password, quindi usa un endpoint standard:

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

Conserva subito la `password` della risposta; viene mostrata una sola volta. Per
accettare chiamate anche solo da Twilio, consulta
[Limita gli IP di origine](/it/guides/sip-addresses).

## 2. Invia le chiamate con contesto

Restituisci questo TwiML per la chiamata che vuoi inoltrare all'agente:

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` è importante: Twilio usa UDP se non viene indicato diversamente.
- `X-Call-ID` contiene il `CallSid`. Twilio non documenta un'intestazione call-id
  propria, quindi aggiungi questa: ThunderPhone la memorizza come
  `external_call_id` della chiamata. `{{CallSid}}` funziona in un TwiML Bin; dal
  tuo server, inserisci il `CallSid` della richiesta in ingresso.
- Aggiungi altro contesto nello stesso modo, ad esempio `&amp;X-Account-Id=12345`. All'interno
  di TwiML, scrivi `&` come `&amp;`, poiché un `&` senza escape non è XML valido. Ognuno raggiunge il
  prompt come variabile, qui `{{sip_x_account_id}}`. Twilio consente intestazioni
  `x-` e `User-to-User`, con codifica percentuale, con l'intero URI sotto i 255 caratteri
  e le intestazioni sotto i 1.024.
- `referUrl` consente a Twilio di accettare il `REFER` dell'agente; senza di esso il trasferimento
  non riesce con l'[errore 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` mantiene il chiamante connesso finché la nuova destinazione
  non risponde, così un trasferimento non riuscito può ricorrere a un fallback.

Il widget **Connetti chiamata a** di Studio non documenta intestazioni personalizzate o
`referUrl`, quindi da Studio inoltra la chiamata a questo TwiML, ad esempio con un
widget **Reindirizzamento TwiML**.

## 3. Recupera la chiamata

L'agente trasferisce con un `REFER` il cui indirizzo di trasferimento contiene l'ID e l'intento del passaggio. Aggiungi questo numero di trasferimento (vedi
[Aggiungi il numero di trasferimento](/it/guides/contact-centers/overview)
e [Intestazioni nell'indirizzo di trasferimento](/it/guides/call-transfers)):

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio invia l'intero indirizzo al tuo `referUrl` come `ReferTransferTarget`, ad
esempio `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Il tuo handler legge le intestazioni dall'indirizzo e restituisce il TwiML per la
destinazione successiva del chiamante. La parte utente dell'indirizzo (`support`)
è a tua scelta, quindi puoi aggiungere un numero di trasferimento per ogni
destinazione e instradare in base a esso.

Questa Twilio Function mette il chiamante in coda su Flex con il passaggio come
attributi dell'attività e cerca il riepilogo tramite l'ID del passaggio. La
ricerca viene eseguita in una Function perché il widget HTTP Request di Studio
non può inviare l'intestazione `Authorization`:

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

Conserva la chiave API nelle variabili d'ambiente della Function. Vedi
[Cerca una chiamata trasferita](/api-reference/calls#look-up-a-handed-off-call)
per gli altri campi.

## Provalo

Chiama un numero Twilio che restituisce il TwiML sopra, chiedi all'agente di
parlare con una persona e verifica che il tuo handler `referUrl` riceva
`ReferTransferTarget` con entrambe le intestazioni e che il chiamante raggiunga
la coda. Quindi apri la chiamata con `GET /v1/calls/{call_id}`:
`external_call_id` deve corrispondere a `CallSid`.

## Limiti

- Twilio limita `Refer-To` a 256 caratteri. ThunderPhone mantiene l'indirizzo a
  254 caratteri e omette un'intestazione che non rientra, quindi mantieni brevi
  i nomi e i valori delle intestazioni.
- Twilio non documenta la lettura delle intestazioni su un `BYE`, quindi un
  ritorno non può riportare il passaggio a Twilio. Usa un `REFER` come sopra.
- Twilio non accetta un `REFER` su una chiamata connessa tramite `<Conference>` o
  `<Queue>`, quindi chiama l'agente con `<Dial><Sip>` come sopra.
