ThunderPhone v3 już działa.Uruchom samodzielnie, od 2¢/min.Przeczytaj komunikat

Contact centers

Połącz z Twilio

Przekierowuj połączenia Twilio do agenta ThunderPhone przez SIP z użyciem CallSid i odbieraj je z powrotem przez swój referUrl, z przekazaniem w adresie transferu.

Twój TwiML wybiera adres SIP agenta z identyfikatorem CallSid połączenia w nagłówku. Gdy rozmówca potrzebuje osoby, agent wysyła SIP REFER, Twilio przekazuje adres transferu wraz z zawartym w nim przekazaniem do procedury obsługi referUrl, a TwiML zwrócony przez procedurę określa, dokąd trafi rozmówca, na przykład do kolejki Flex.

Zanim zaczniesz

  • Agent ThunderPhone i klucz API organizacji.
  • Twilio Programmable Voice oraz miejsce do obsługi TwiML i procedury obsługi referUrl: własny serwer albo TwiML Bin i Twilio Function. Flex jest opcjonalny.

1. Utwórz punkt końcowy SIP

Element <Sip> w Twilio przyjmuje nazwę użytkownika i hasło, więc użyj standardowego punktu końcowego:

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

Od razu zapisz password z odpowiedzi; jest wyświetlane tylko raz. Aby akceptować połączenia wyłącznie z Twilio, zobacz Ogranicz źródłowe adresy IP.

2. Wysyłaj połączenia z kontekstem

Zwróć ten TwiML dla połączenia, które chcesz przekazać agentowi:

<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 jest wymagany: Twilio używa UDP, jeśli nie zostanie wskazane inaczej.
  • X-Call-ID zawiera CallSid. Twilio nie dokumentuje własnego nagłówka call-id, więc dodaj ten: ThunderPhone zapisuje go jako external_call_id połączenia. {{CallSid}} działa w TwiML Bin; na własnym serwerze zapisz CallSid przychodzącego żądania.
  • Dodaj więcej kontekstu w ten sam sposób, na przykład &amp;X-Account-Id=12345. W TwiML zapisz & jako &amp;, ponieważ samodzielne & jest nieprawidłowym XML. Każdy z nich trafia do promptu jako zmienna, tutaj {{sip_x_account_id}}. Twilio zezwala na nagłówki x- i User-to-User zakodowane procentowo, przy czym cały URI musi mieć mniej niż 255 znaków, a nagłówki mniej niż 1 024.
  • referUrl umożliwia Twilio zaakceptowanie REFER agenta; bez niego transfer kończy się błędem 13802. answerOnBridge="true" utrzymuje połączenie z rozmówcą do czasu odebrania przez nowy cel, dzięki czemu w razie nieudanego transferu można zastosować rozwiązanie awaryjne.

Widget Połącz rozmowę z w Studio nie dokumentuje niestandardowych nagłówków ani referUrl, więc ze Studio przekaż połączenie do tego TwiML, na przykład za pomocą widgetu Przekierowanie TwiML.

3. Odbierz połączenie z powrotem

Agent przekazuje połączenie za pomocą REFER, którego adres przekazania zawiera identyfikator i intencję przekazania. Dodaj ten numer przekazania (zobacz Dodawanie numeru przekazania oraz Nagłówki w adresie przekazania):

{
  "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 wysyła cały adres do referUrl jako ReferTransferTarget, na przykład <sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>. Twój handler odczytuje z niego nagłówki i zwraca TwiML określający, dokąd następnie trafia rozmówca. Część użytkownika adresu (support) wybierasz samodzielnie, więc możesz dodać jeden numer przekazania dla każdego miejsca docelowego i kierować połączenia na jego podstawie.

Ta funkcja Twilio umieszcza rozmówcę w kolejce Flex z przekazaniem jako atrybutami zadania i wyszukuje podsumowanie według identyfikatora przekazania. Wyszukiwanie działa w funkcji, ponieważ widżet Żądanie HTTP w Studio nie może wysłać nagłówka 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);
};

Przechowuj klucz API w zmiennych środowiskowych funkcji. Zobacz Wyszukiwanie przekazanego połączenia, aby poznać pozostałe pola.

Przetestuj

Zadzwoń na numer Twilio, który zwraca powyższy TwiML, poproś agenta o połączenie z osobą i sprawdź, czy handler referUrl otrzymuje ReferTransferTarget z oboma nagłówkami oraz czy rozmówca trafia do kolejki. Następnie otwórz połączenie za pomocą GET /v1/calls/{call_id}: wartość external_call_id powinna być równa CallSid.

Ograniczenia

  • Twilio ogranicza Refer-To do 256 znaków. ThunderPhone ogranicza adres do 254 znaków i pomija nagłówek, który się nie mieści, dlatego nazwy i wartości nagłówków powinny być krótkie.
  • Twilio nie dokumentuje odczytywania nagłówków w BYE, więc powrót nie może przekazać danych przekazania z powrotem do Twilio. Użyj REFER, jak powyżej.
  • Twilio nie akceptuje REFER w połączeniu zestawionym przez <Conference> ani <Queue>, dlatego wybieraj numer agenta przez <Dial><Sip>, jak powyżej.