ThunderPhone v3 è online.Attivazione self-service, da 2¢/min.Leggi l’annuncio

Contact centers

Connettiti da Twilio

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

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 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:

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.

2. Invia le chiamate con contesto

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

<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. 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 e Intestazioni nell'indirizzo di trasferimento):

{
  "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:

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 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.