Open in
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-IDcontiene ilCallSid. Twilio non documenta un'intestazione call-id propria, quindi aggiungi questa: ThunderPhone la memorizza comeexternal_call_iddella chiamata.{{CallSid}}funziona in un TwiML Bin; dal tuo server, inserisci ilCallSiddella richiesta in ingresso.- Aggiungi altro contesto nello stesso modo, ad esempio
&X-Account-Id=12345. All'interno di TwiML, scrivi&come&, poiché un&senza escape non è XML valido. Ognuno raggiunge il prompt come variabile, qui{{sip_x_account_id}}. Twilio consente intestazionix-eUser-to-User, con codifica percentuale, con l'intero URI sotto i 255 caratteri e le intestazioni sotto i 1.024. referUrlconsente a Twilio di accettare ilREFERdell'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-Toa 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 unREFERcome sopra. - Twilio non accetta un
REFERsu una chiamata connessa tramite<Conference>o<Queue>, quindi chiama l'agente con<Dial><Sip>come sopra.