Open in
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=tlsjest wymagany: Twilio używa UDP, jeśli nie zostanie wskazane inaczej.X-Call-IDzawieraCallSid. Twilio nie dokumentuje własnego nagłówka call-id, więc dodaj ten: ThunderPhone zapisuje go jakoexternal_call_idpołączenia.{{CallSid}}działa w TwiML Bin; na własnym serwerze zapiszCallSidprzychodzącego żądania.- Dodaj więcej kontekstu w ten sam sposób, na przykład
&X-Account-Id=12345. W TwiML zapisz&jako&, ponieważ samodzielne&jest nieprawidłowym XML. Każdy z nich trafia do promptu jako zmienna, tutaj{{sip_x_account_id}}. Twilio zezwala na nagłówkix-iUser-to-Userzakodowane procentowo, przy czym cały URI musi mieć mniej niż 255 znaków, a nagłówki mniej niż 1 024. referUrlumożliwia Twilio zaakceptowanieREFERagenta; 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-Todo 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żyjREFER, jak powyżej. - Twilio nie akceptuje
REFERw połączeniu zestawionym przez<Conference>ani<Queue>, dlatego wybieraj numer agenta przez<Dial><Sip>, jak powyżej.