Przejdź do treści

Integracje - Webhooks

Webhook jest wyzwalany przez: wykonywanie połączenia, odebranie połączenie , rozłączenie połączenia itp. Następnie VoIPstudio platforma wysyła żądanie HTTPS (POST) na adres URL skonfigurowany dla Webhook - serwera internetowego innej firmy (API). Dowiedz się więcej więcej na Wikipedia

web-hook.png

Figure 9.1 Włączanie i konfigurowanie Webhook
  1. Kliknij Integracje.
  2. Przewiń w dół do skecji Webshooks.
  3. Kliknij Add Webhook aby dodać nowy.
  4. Wprowadź nazwę nowego Webhook.
  5. Wprowadź nazwy monitorowanych zdarzeń. Uwaga Call State change obejmuje wszystkie zdarzenia.
  6. Wprowadź adres URL używany przez aplikację.
  7. Aby edytować Webhook kliknij na jego nazwę.
  8. W każdej chwili możesz wyłączyć Webhook.

UWAGA: Obsługiwany jest tylko protokół HTTPS.

UWAGA: Aby adres URL został zapisany musi odpowiadać na żądania Https.

Możliwe zdarzenia

Dzięki VoIPtudio WebHooks monitorowane są następujące statusy połączeń:

  • Połączenie nieodebrane
  • Trwa łączenie
  • Połączono
  • Połączenie zakończone
  • Zmiana stanu połączenia - obejmuje wszystkie poprzednie typy zdarzeń. Jest wyzwalany przy każdej zmianie stanu połączenia: DZWONI, PODŁĄCZONE, ON HOLD, ROZŁĄCZONE.

Monitorowane zdarzenia prezentują stan połączenia i są zgodne z komunikatami sygnalizacyjnymi SIP, jak opisano poniżej:

  • INITIAL: SIP INVITE zostaje wysłany do odpowiedniego punktu końcowego (Telefon).
  • RINGING: odpowiedź punktu końcowego z SIP INVITE. Wskazuje, że punkt końcowy jest aktywny i dzwoni.
  • CONNECTED: komunikat SIP 200 wskazuje, że użytkownik odebrał połączenie.
  • ON_HOLD: Rozmowa została wstrzymana. Odpowiada to SIP INVITE body: a=sendonly
  • HANGUP: Połączenie zostało zakończone. Odpowiada to SIP BYE Message.

Oprócz zdarzeń dotyczących stanu połączeń dostępne są następujące zdarzenia dodatkowe:

  • Otrzymano SMS

Atrybuty wydarzeń

Wydarzenia są dostarczane w formacie HTTPs POST requests with JSON body - na przykład:

{
"id":"uk003.608920d55f7ac3.77053295",
"event_time":"2021-04-28 08:46:13",
"event_name":"call.hangup",
"call_id":139543232,
"state":"HANGUP",
"connected_at":"2021-04-28 08:46:02",
"start_time":"2021-04-28 08:45:55",
"context":"LOCAL_USER",
"destination":"in",
"duration":11,
"t_cause":"Normal Clearing",
"src":"447854740947",
"src_id":"0",
"src_name":"\"442035141598\" <2035141598>",
"src_hash":"fe5935cefbc82fc4e924bdaa21342a49c18c5dd9",
"dst":"441183211001",
"dst_id":"10002",
"dst_name":"John Smith"
}

Atrybuty są następujące:

  • id (string) - unikalny identyfikator zdarzenia
  • event_time (string) - czas zdarzenia R-M-D H:i:s w formacie UTC
  • event_name (string) - nazwa wydarzenia, jedno z:
    • call.initial - Inicjowanie połączenia
    • call.ringing - Dzwoni
    • call.missed - Nieodebrane połączenie
    • call.connected -Połączenie zostało nawiązane
    • call.hangup - Połączenie zostało zakończone
    • call.hold - Połączenie jest zawieszone
    • call.unhold - Połączenie jest przełączone z onhold
  • call_id (integer) - to jest numeryczny identyfikator połączenia. Może być później używany do uzyskiwania dostępu do zasobów za pośrednictwem REST API. Relacja z zasobami REST API jest następująca:
    • call.id - przykładowe żądanie REST API:
    • cdr.live_id - przykładowe żądanie REST API: GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
    • monitor.live_id - example REST API request: GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
  • state (string) - stan połączenia, jeden z:
    • INITIAL -Początkowy stan połączenia
    • ACCEPTED - Click 2 call został zaakceptowany
    • RINGING -Dzwoni
    • CONNECTED - Połączenie zostało nawiązane
    • ON_HOLD - Połączenie jest zawieszone
    • HANGUP - Połączenie zostało zakończone
  • connected_at (string) -czas, kiedy połączenie zostało nawiązane w formacie R-M-Dformat strefy czasowej UTC. Domyślnie null
  • start_time (string) - czas rozpoczęcia rozmowy w formacie R-M-D format strefy czasowej UTC
  • context (string) - kontekst połączenia w systemie PBX
  • destination (string) - in dla połączeń przychodzących , out dla połączeń wychodzących
  • duration (integer) - czas trwania połączenia w sekundach
  • t_cause (string) - Przyczyna zakończenia połączenia
  • src (string) - Numer źródła połączenia
  • src_id (integer) - Numeryczny identyfikator źródła połączenia
  • src_name (string) -Nazwa źródła połączenia
  • dst (string) - Numer odbiorcy połączenia
  • dst_id (integer) - Numeryczny identyfikator miejsca docelowego połączenia
  • dst_name (string) - Nazwa odbiorcy połączenia

Atrybuty zdarzenia otrzymanego SMS-a są następujące:

  • id (string) - unikalny identyfikator zdarzenia
  • event_time (string) - czas zdarzenia R-M-D H:i:s w formacie UTC
  • event_name (string) - nazwa wydarzenia sms.received
  • customer_id (integer) - Numeryczny identyfikator Konta Klienta, który otrzymał wiadomość SMS
  • user_id (integer) - Numeryczny identyfikator konta użytkownika, który otrzymał wiadomość SMS (optional, default: null)
  • from_no (string) - numer telefonu nadawcy wiadomości SMS
  • to_no (string) - numer telefonu, który otrzymał wiadomość SMS
  • text (string) - treść otrzymanej wiadomości

Powiązane punkty końcowe API REST

Po otrzymaniu Webhook zdarzenia jak w przykładzie powyżej (call_id = 139543232), można pobrać i zaktualizować zasoby połączeń via REST API:

GET /v1.1/calls/139543232

i przekierować połączenie na numer wewnętrzny 2002:

PATCH /v1.1/calls/139543232
{
"dst": "2002"
}

Uwaga: /calls REST API reprezentuje aktywne trwające połączenie.Po zakończeniu rozmowy i nastąpieniu call.hangup nie będzie dostępny pod adresem /calls endpoint. Można uzyskać do niego dostęp pod adresem /cdrs (Raport szczegółów połączeń) oraz /monitors (Call Recordings) punkty końcowe przy użyciu filtra live_id atrybut z wartością call_id ze zdarzenia Webhook na przykład:

GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

lub

GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

Atrybuty kontekstowe - Kolejki

Jak widzieliśmy, context może mieć kilka wartości w zależności od obiektu, w którym je generujemy. Jeśli chcemy monitorować zdarzenia występujące u użytkownika, będziemy musieli poszukać atrybutu z wartością kontekstu LOCAL_USER jeśli chcemy monitorować zdarzenia, które występują w kolejce, filtrujemy według QUEUE.

Uwaga: aby rozpocząć odbieranie zdarzeń kolejki, będziemy potrzebować co najmniej jednego webhooka typu Zmiana stanu połączenia ponieważ to generuje zdarzenia dla każdego obiektu.

Ten kontekst zdarzenia pozwala nam zidentyfikować połączenie, które nie zostało odebrane przez żadnego agenta oraz przyczynę np. osiągnięto maksymalny czas oczekiwania, użytkownik zakończył połączenie ect. Aby zidentyfikować nieodebrane połączenie w kolejce zamiast sprawdzać Context = User szukamy wydarzenia z context:Queue i event_name:call.missed.

Rozwiązywanie problemów z Webhooks

Szczegółowe raporty połączeń VoIPstudio umożliwia monitorowanie przepływu wszystkich pakietów SIP w widoku graficznym dla każdego połączenia.Wyświetla również powiadomienia webhooków wysyłane na Twój adres URL, w tym ich zawartość. Może to być bardzo przydatne do rozwiązywania problemów z wdrażaniem powiadomień elementów webhook.

Wystarczy przejrzeć szczegółowy raport połączeń, kliknąć odpowiednie zaproszenia i sprawdzić przesłane wydarzenia oraz ich treść. Powinno to być zgodne z powiadomieniem, które otrzymałeś na serwerze. Wykonaj poniższe czynności:

webhooks-troubleshooting.png

Figure 9.2 Rozwiązywanie problemów z Webhooks
  1. Z panelu administracyjnego otwórz panel sekcję Historia.
  2. Kliknij CDR, spowoduje to otwarcie listy ostatnich połączeń na platformie VoIPstudio.
  3. Zidentyfikuj i kliknij połączenie, aby wyświetlić szczegółowe informacje.
  4. Następnie zidentyfikuj kolumnę serwera API.
  5. Wyświetli się jedno żądanie POST wysyłane na serwer dla każdego zdarzenia, dla którego masz ustawione zdarzenie elementu Webhook.
  6. Szczegóły Webhook zostaną wyświetlone tutaj.