ThunderPhone v3 est disponible.En libre-service, à partir de 2 ¢/min.Découvrir l’annonce

Contact centers

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=tls est important : Twilio utilise UDP sauf indication contraire.
  • X-Call-ID transmet le CallSid. Twilio ne documente pas d’en-tête d’identifiant d’appel natif, ajoutez donc celui-ci : ThunderPhone le stocke comme external_call_id de l’appel. {{CallSid}} fonctionne dans un TwiML Bin ; depuis votre propre serveur, écrivez le CallSid de la requête entrante.
  • Ajoutez davantage de contexte de la même manière, par exemple &amp;X-Account-Id=12345. Dans TwiML, écrivez & sous la forme &amp;, 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êtes x- et User-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.
  • referUrl permet à Twilio d’accepter le REFER de 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 un REFER comme ci-dessus.
  • Twilio n'accepte pas de REFER sur un appel connecté via <Conference> ou <Queue>. Composez donc le numéro de l'agent avec <Dial><Sip> comme ci-dessus.