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

Figure 66.1 Włączanie i konfigurowanie Webhook

Kliknij Integracje.
Przewiń w dół do skecji Webshooks.
Kliknij Add Webhook aby dodać nowy.
Wprowadź nazwę nowego Webhook.
Wprowadź nazwy monitorowanych zdarzeń. Uwaga Call State change obejmuje wszystkie zdarzenia.
Wprowadź adres URL używany przez aplikację.
Aby edytować Webhook kliknij na jego nazwę.
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:

Figure 66.2 Rozwiązywanie problemów z Webhooks

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