Open in
Connecter depuis Twilio
Envoyez des appels Twilio à un agent ThunderPhone via SIP avec le CallSid, puis récupérez-les via votre referUrl avec le transfert dans l’adresse de transfert.
Votre TwiML compose l’adresse SIP de l’agent avec le CallSid de l’appel dans un en-tête.
Lorsque l’appelant doit joindre une personne, l’agent envoie un REFER SIP, Twilio transmet l’adresse de transfert contenant le relais à votre gestionnaire referUrl, et le TwiML renvoyé par votre gestionnaire détermine où va l’appelant, par exemple vers une file Flex.
Avant de commencer
- Un agent ThunderPhone et une clé API d’organisation.
- Twilio Programmable Voice, ainsi qu’un emplacement pour servir le TwiML et un
gestionnaire
referUrl: votre propre serveur, ou un TwiML Bin et une Twilio Function. Flex est facultatif.
1. Créez le point de terminaison SIP
Le composant <Sip> de Twilio accepte un nom d’utilisateur et un mot de passe, utilisez donc un point de terminaison 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"}'Enregistrez immédiatement le password de la réponse ; il n’est affiché qu’une seule fois. Pour
n’accepter que les appels provenant de Twilio, consultez
Restreindre les IP sources.
2. Envoyez les appels avec du contexte
Renvoyez ce TwiML pour l’appel que vous souhaitez transmettre à l’agent :
<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=tlsest important : Twilio utilise UDP sauf indication contraire.X-Call-IDtransmet leCallSid. Twilio ne documente pas d’en-tête d’identifiant d’appel natif, ajoutez donc celui-ci : ThunderPhone le stocke commeexternal_call_idde l’appel.{{CallSid}}fonctionne dans un TwiML Bin ; depuis votre propre serveur, écrivez leCallSidde la requête entrante.- Ajoutez davantage de contexte de la même manière, par exemple
&X-Account-Id=12345. Dans TwiML, écrivez&sous la forme&, car un&seul n’est pas un XML valide. Chaque valeur atteint le prompt sous forme de variable, ici{{sip_x_account_id}}. Twilio autorise les en-têtesx-etUser-to-User, encodés en pourcentage, avec une URI entière de moins de 255 caractères et des en-têtes de moins de 1 024 caractères. referUrlpermet à Twilio d’accepter leREFERde l’agent ; sans lui, le transfert échoue avec l’erreur 13802.answerOnBridge="true"maintient l’appelant connecté jusqu’à ce que la nouvelle destination réponde, afin de prévoir une solution de repli en cas d’échec du transfert.
Le widget Connecter l’appel à de Studio ne documente pas les en-têtes personnalisés ni
referUrl. Depuis Studio, transmettez donc l’appel à ce TwiML, par exemple avec un
widget Redirection TwiML.
3. Récupérer l'appel
L'agent effectue le transfert avec un REFER dont l'adresse de transfert contient
l'identifiant et l'intention de passation. Ajoutez ce numéro de transfert (voir
Ajouter le numéro de transfert
et En-têtes dans l'adresse de transfert) :
{
"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 envoie l'adresse entière à votre referUrl sous la forme de ReferTransferTarget, par
exemple <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>.
Votre gestionnaire lit les en-têtes qu'elle contient et renvoie le TwiML correspondant à la prochaine
destination de l'appelant. La partie utilisateur de l'adresse (support) est à votre
choix. Vous pouvez donc ajouter un numéro de transfert par destination et effectuer le
routage en fonction de celui-ci.
Cette Function Twilio met l'appelant en file d'attente dans Flex avec la passation comme
attributs de tâche et recherche le résumé par identifiant de passation. La recherche s'exécute dans une
Function, car le widget HTTP Request de Studio ne peut pas envoyer l'en-tête
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);
};Conservez la clé API dans les variables d'environnement de la Function. Consultez Rechercher un appel transféré pour les autres champs.
Tester
Appelez un numéro Twilio qui renvoie le TwiML ci-dessus, demandez à l'agent de parler à une personne,
puis vérifiez que votre gestionnaire referUrl reçoit ReferTransferTarget avec les deux
en-têtes et que l'appelant atteint la file d'attente. Ouvrez ensuite l'appel avec
GET /v1/calls/{call_id} : external_call_id doit correspondre au CallSid.
Limites
- Twilio limite
Refer-Toà 256 caractères. ThunderPhone limite l'adresse à 254 caractères et omet tout en-tête qui ne tient pas. Gardez donc les noms et valeurs d'en-tête courts. - Twilio ne documente pas la lecture des en-têtes sur un
BYE. Un retour ne peut donc pas retransmettre la passation à Twilio. Utilisez unREFERcomme ci-dessus. - Twilio n'accepte pas de
REFERsur un appel connecté via<Conference>ou<Queue>. Composez donc le numéro de l'agent avec<Dial><Sip>comme ci-dessus.