Zum Inhalt

Integrationen - Webhooks

Webhooks werden durch ein Anrufereignis ausgelöst, wie z. B. einen klingelnden Anruf, einen angenommenen Anruf, einen aufgelegten Anruf usw. Wenn dieses Ereignis eintritt, stellt die VoIPstudio-Plattform eine HTTPS-Anfrage (POST) an die für den Webhook konfigurierte URL - einen Webserver (API) eines Drittanbieters. Siehe mehr auf Wikipedia

webhooks-config.png

Figure 66.1 Aktivieren und Konfigurieren von Webhooks.
  1. Klicken Sie auf Integrationen.
  2. Scrollen Sie nach unten zu Webshooks und Aktivieren.
  3. Wählen Sie Webhook hinzufügen, um einen neuen zu erstellen.
  4. Geben Sie einen beliebigen Namen für den neuen Webhook ein, um ihn zu identifizieren.
  5. Wählen Sie die Ereignisse aus, auf die Sie warten möchten. Beachten Sie, dass der Typ Call State change alle Ereignisse einschließt.
  6. Geben Sie die von Ihrer Anwendung verwendete URL ein.
  7. Um einen Webhook zu bearbeiten, klicken Sie einfach auf den Namen.
  8. Wenn nicht mehr benötigt, klicken Sie einfach auf Webhooks deaktivieren.

HINWEIS: Es wird nur das HTTPS-Protokoll unterstützt.

HINWEIS: Damit eine URL gespeichert werden kann, muss diese gültig sein und auf https-Anfragen antworten.

Verfügbare Ereignisse

Mit VoIPtudio WebHooks überwachen wir folgende Kategorien von Anrufstatusereignissen:

  • Entgangener Anruf
  • Anruf läutet
  • Anruf verbunden
  • Anruf beendet
  • Call State Change - dieser letzte umfasst alle vorherigen Ereignistypen. Er wird bei jeder Änderung des Anrufstatus ausgelöst: INITIAL, KLINGELN, VERBUNDEN, ON_HOLD, AUFLEGEN.

Beachten Sie, dass überwachte Ereignisse den Anrufstatus anzeigen und mit SIP-Signalisierungsmeldungen übereinstimmen, wie unten beschrieben:

  • INITIAL: SIP INVITE senden an den entsprechenden Endpunkt (Telefon).
  • RINGING: Antwort des Endpunkts von SIP INVITE. Es zeigt an, dass der Endpunkt aktiv ist und es bereits klingelt.
  • CONNECTED: SIP 200-Nachricht, die anzeigt, dass der Benutzer den Anruf angenommen hat.
  • ON_HOLD: Der Anruf ist pausiert. Dies entspricht einem SIP INVITE mit body: a=sendonly
  • HANGUP: Zeigt an, dass der Anruf beendet wurde. Dies entspricht einer SIP BYE Message.

Neben den Ereignissen zum Anrufstatus sind die folgenden zusätzlichen Ereignisse verfügbar:

  • Empfangene SMS

Ereignis-Attribute

Ereignisse werden als HTTPs POST-Anfragen mit JSON-Body geliefert - zum Beispiel:

{
  "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>",
  "dst":"441183211001",
  "dst_id":"10002",
  "dst_name":"John Smith"
}

Die Attribute sind wie folgt:

  • id (String) - eindeutige ID eines Ereignisses
  • event_time (string) - Zeit eines Ereignisses im Format J-m-d H:i:s UTC-Zeitzone
  • event_name (string) - Name eines Ereignisses, einer von:
    • call.initial - Anruf im Ausgangszustand
    • call.ringing - Anruf läutet
    • call.missed - Verpasster (unbeantworteter) Anruf
    • call.connected - Anruf ist verbunden
    • call.hangup - Anruf wird beendet
    • call.hold - Anruf wird gehalten
    • call.unhold - Anruf wird aufgehoben
  • call_id (Ganzzahl) - dies ist die numerische ID des Aufrufs. Sie kann später für den Zugriff auf Ressourcen über die REST-API verwendet werden. Die Beziehung zu REST-API-Ressourcen ist:
    • call.id - Beispiel REST-API-Anfrage:
    • cdr.live_id - Beispiel REST-API-Anfrage: GET /v1.1/cdrs?filter=[{"property": "live_id", "operator":"=", "value":"{call.id}"}]
    • monitor.live_id - Beispiel einer REST-API-Anfrage: GET /v1.1/monitors?filter=[{"property": "live_id", "operator":"=", "value":"{call.id}"}]
  • state (String) - Zustand des Aufrufs, einer von:
    • INITIAL - Anfangszustand des Anrufs
    • ACCEPTED - Click-2-Ruf wurde angenommen
    • RINGING - Ziel wird angerufen
    • CONNECTED - Anruf ist verbunden
    • ON_HOLD - Anruf wird gehalten
    • HANGUP - Anruf wird beendet
  • connected_at (String) - Uhrzeit, zu der der Anruf verbunden wurde, im Format Y-m-d H:i:s UTC-Zeitzone. Voreinstellung null
  • start_time (string) - Uhrzeit, zu der der Anruf gestartet wurde im Format Y-m-d H:i:s UTC timezone.
  • context (string) - Kontext des Anrufs innerhalb der TK-Anlage
  • destination (string) - in für eingehenden Anruf, out für ausgehenden Anruf
  • duration (Integer) - Dauer des Anrufs in Sekunden
  • t_cause (string) - Beendigungsursache
  • src (string) - Nummer der Rufquelle
  • src_id (integer) - Numerische ID der Rufquelle
  • src_name (string) - Name der Rufquelle
  • dst (String) - Nummer des Anrufziels
  • dst_id (integer) - Numerische ID des Anrufziels
  • dst_name (String) - Name des Rufziels

SMS-Empfangsereignisattribute sind wie folgt:

  • id (string) - eindeutige ID eines Ereignisses
  • event_time (string) - Zeit eines Ereignisses im Format Y-m-d H:i:s UTC-Zeitzone
  • event_name (string) - Name eines Ereignisses sms.received
  • customer_id` (integer) - Numerische ID des Kundenkontos, das die SMS-Nachricht erhalten hat
  • user_id (integer) - Numerische ID des Benutzerkontos, das die SMS-Nachricht erhalten hat (optional, Standard: null)
  • from_no (string) - Absenderrufnummer
  • to_no` (string) - Rufnummer, die die SMS-Nachricht erhalten hat
  • Text" (String) - Inhalt der empfangenen Nachricht

Zugehörige REST-API-Endpunkte

Nach dem Empfang des Webhook-Ereignisses wie im obigen Beispiel (call_id = 139543232) kann man die Anrufressource über die REST-API abrufen und aktualisieren:

GET /v1.1/calls/139543232

und den Anruf an die Nebenstelle 2002 weiterleiten:

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

Hinweis: Die REST-API-Ressource /calls repräsentiert einen aktiven laufenden Anruf. Sobald der Anruf beendet und das Ereignis call.hangup empfangen wurde, ist er nicht mehr am Endpunkt /calls verfügbar. Stattdessen kann auf sie über die Endpunkte /cdrs (Call Details Report) und /monitors (Call Recordings) zugegriffen werden, indem ein Filter auf das Attribut live_id mit dem Wert call_id aus dem Webhook-Ereignis verwendet wird, zum Beispiel:

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

or

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

Fehlersuche bei Webhooks

Mit den detaillierten Berichten aus dem VoIPstudio-Dashboard können Kunden den Workflow aller SIP-Pakete in einer grafischen Ansicht für jeden einzelnen Anruf überwachen. Es zeigt auch die Webhooks-Benachrichtigungen an, die an Ihre Listening-URL gesendet wurden, einschließlich ihres Inhalts. Dies kann bei der Fehlersuche in Ihrer Webhooks-Benachrichtigungsverteilung sehr nützlich sein.

Sie brauchen nur den Call Detailed Report zu durchsuchen und auf die entsprechenden Anrufe zu klicken, um die übermittelten Ereignisse und deren Inhalt zu überprüfen. Dies sollte mit der Benachrichtigung übereinstimmen, die Sie auf dem Server erhalten haben. Bitte führen Sie die folgenden Schritte aus:

webhooks-troubleshooting.png

Figure 66.2 Fehlersuche bei Webhooks.
  1. Öffnen Sie im Admin-Dashboard den Abschnitt History.
  2. Klicken Sie auf CDR, um eine Liste der letzten Anrufe zu öffnen, die unter der Plattform VoIPstudio verarbeitet wurden.
  3. Identifizieren Sie den Anruf, den Sie prüfen möchten, und klicken Sie darauf, um detaillierte Informationen zu dem entsprechenden Anruf zu erhalten.
  4. Identifizieren Sie unter Call Flow die Spalte Ihres API-Servers.
  5. Sie müssen sehen, dass für jedes Ereignis, das Sie als Webhook-Ereignis eingestellt haben, eine POST-Anfrage an den Server gesendet wird. Klicken Sie darauf, um sie zu erweitern.
  6. Hier werden die Details der Webhook-Post-Antwort angezeigt.