ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Contact centers

Pripojenie z Twilio

Presmerujte hovory z Twilio na agenta ThunderPhone cez SIP pomocou CallSid a vráťte ich späť prostredníctvom svojho referUrl s odovzdaním v adrese prenosu.

Váš TwiML vytočí SIP adresu agenta s CallSid hovoru v hlavičke. Keď volajúci potrebuje osobu, agent odošle SIP REFER, Twilio odovzdá adresu prenosu s presmerovaním vo vnútri do vášho obslužného programu referUrl a TwiML, ktorý váš obslužný program vráti, rozhodne, kam bude volajúci smerovaný, napríklad do frontu Flex.

Skôr než začnete

  • Agent ThunderPhone a organizačný kľúč API.
  • Twilio Programmable Voice a miesto na poskytovanie TwiML a obslužného programu referUrl: vlastný server alebo TwiML Bin a Twilio Function. Flex je voliteľný.

1. Vytvorte SIP koncový bod

<Sip> služby Twilio používa používateľské meno a heslo, preto použite štandardný koncový bod:

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"}'

password z odpovede si ihneď uložte; zobrazí sa iba raz. Ak chcete prijímať hovory aj iba z Twilio, pozrite si Obmedzenie zdrojových IP adries.

2. Odošlite hovory s kontextom

Pre hovor, ktorý chcete odovzdať agentovi, vráťte tento TwiML:

<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 je dôležité: Twilio používa UDP, ak mu neurčíte inak.
  • X-Call-ID prenáša CallSid. Twilio nedokumentuje vlastnú hlavičku call-id, preto pridajte túto: ThunderPhone ju uloží ako external_call_id hovoru. {{CallSid}} funguje v TwiML Bin; z vlastného servera zapíšte CallSid prichádzajúcej požiadavky.
  • Rovnakým spôsobom pridajte ďalší kontext, napríklad &amp;X-Account-Id=12345. V rámci TwiML zapíšte & ako &amp;, pretože samotné & je neplatné XML. Každý sa dostane do výzvy ako premenná, tu {{sip_x_account_id}}. Twilio povoľuje hlavičky x- a User-to-User kódované percentami, pričom celý identifikátor URI má menej ako 255 znakov a hlavičky menej ako 1 024 znakov.
  • referUrl umožňuje službe Twilio prijať REFER agenta; bez neho prenos zlyhá s chybou 13802. answerOnBridge="true" ponechá volajúceho pripojeného, kým nová destinácia neodpovie, takže pri zlyhaní prenosu je možné použiť záložné riešenie.

Widget Pripojiť hovor k v Studio nedokumentuje vlastné hlavičky ani referUrl, preto zo Studio odovzdajte hovor tomuto TwiML, napríklad pomocou widgetu Presmerovanie TwiML.

3. Prijmite hovor späť

Agent presmeruje hovor pomocou REFER, ktorého adresa presmerovania obsahuje identifikátor a zámer odovzdania. Pridajte toto číslo presmerovania (pozrite si Pridanie čísla presmerovania a Hlavičky v adrese presmerovania):

{
  "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 odošle celú adresu do vášho referUrl ako ReferTransferTarget, napríklad <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>. Váš obslužný program z nej načíta hlavičky a vráti TwiML pre ďalšie smerovanie volajúceho. Používateľskú časť adresy (support) si môžete zvoliť, takže môžete pridať jedno číslo presmerovania pre každé cieľové miesto a smerovať podľa neho.

Táto funkcia Twilio zaradí volajúceho do frontu Flex s odovzdaním ako atribútmi úlohy a vyhľadá zhrnutie podľa identifikátora odovzdania. Vyhľadávanie sa vykonáva vo funkcii, pretože miniaplikácia HTTP Request v Studio nemôže odoslať hlavičku 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);
};

Kľúč API uchovávajte v premenných prostredia funkcie. Ďalšie polia nájdete v časti Vyhľadanie odovzdaného hovoru.

Otestujte to

Zavolajte na číslo Twilio, ktoré vráti vyššie uvedený TwiML, požiadajte agenta o spojenie s osobou a overte, že váš obslužný program referUrl prijme ReferTransferTarget s oboma hlavičkami a že sa volajúci dostane do frontu. Potom otvorte hovor pomocou GET /v1/calls/{call_id}: hodnota external_call_id by mala byť CallSid.

Obmedzenia

  • Twilio obmedzuje Refer-To na 256 znakov. ThunderPhone udržiava adresu na 254 znakoch a vynechá hlavičku, ktorá sa nezmestí, preto názvy a hodnoty hlavičiek udržujte krátke.
  • Twilio nedokumentuje čítanie hlavičiek pri BYE, preto návrat nemôže preniesť odovzdanie späť do Twilio. Použite REFER, ako je uvedené vyššie.
  • Twilio neprijíma REFER pri hovore pripojenom cez <Conference> alebo <Queue>, preto agenta vytočte pomocou <Dial><Sip>, ako je uvedené vyššie.