Protokollierungsaktivität mit einem Webhook

Plus

Sie können die Aktivität protokollieren, indem Sie jedes Mal, wenn ein Kunde Eingaben an den Assistenten schickt, einen Aufruf an einen externen Service oder eine Anwendung senden.

Ein Webhook ist ein Mechanismus, mit dem Sie ein externes Programm basierend auf Ereignissen in Ihrem Programm aufrufen können.

Diese Funktion steht nur Benutzern mit Plus- und Enterprise-Plan zur Verfügung. Der Plus-Plan lässt nicht mehr als 5 Protokoll-Webhooks pro Instanz zu. Dieser Grenzwert gilt nicht für Enterprise Plan-Instanzen.

Fügen Sie Ihrem Assistenten einen Log-Webhook hinzu, wenn Sie einen externen Dienst zur Protokollierung von Aktivitäten verwenden möchten. Sie können zwei Arten von Aktivitäten protokollieren:

Nachrichten und Antworten: Der Log-Webhook wird jedes Mal ausgelöst, wenn der Assistent auf eine Eingabe des Kunden reagiert. Sie können diese Option als Alternative zur integrierten Analysefunktion verwenden, um die Protokollierung selbst zu verarbeiten. (Weitere Informationen zur integrierten Analyseunterstützung finden Sie im Abschnitt zur Überprüfung des gesamten Assistenten auf einen Blick.)

Wenn Sie einen benutzerdefinierten Kanal verwenden, funktioniert der Log-Webhook nur mit der API v2 /message (zustandslos und zustandsbehaftet). Weitere Informationen finden Sie in der API-Referenz. Alle integrierten Kanalintegrationen verwenden diese API.
Anrufdetailaufzeichnungen (Call Detail Records, CDRs ): Der Log-Webhook wird nach jedem Telefonanruf eines Benutzers an Ihren Assistenten ausgelöst, der die Telefonintegration verwendet. Ein Datensatz mit Anrufdetails (Call Detail Record, CDR) ist ein zusammenfassender Bericht, der die Details eines Telefonanrufs dokumentiert, einschließlich Telefonnummern, Anruflänge, Latenzzeit und anderer Diagnoseinformationen. CDR-Aufzeichnungen sind nur für Assistenten, die die Telefonintegration verwenden.

Der Protokoll-Webhook gibt nichts an Ihren Assistenten zurück.

Beachten Sie bei Umgebungen, in denen private Endpunkte verwendet werden, dass ein Webhook Daten über das Internet sendet.

Webhook definieren

Sie können eine Webhook-URL für die Protokollierung jeder eingehenden Nachricht oder jedes CDR-Ereignisses definieren.

Der programmgesteuerte Aufruf an den externen Service muss die folgenden Voraussetzungen erfüllen:

Der Aufruf muss eine HTTP-Anforderung POST sein.

Führen Sie die folgenden Schritte aus, um die Webhookdetails hinzufügen:

Öffnen Sie in Ihrem Assistenten die Umgebung, in der Sie den Webhook konfigurieren möchten.
Klicken Sie auf das Symbol , um die Umgebungseinstellungen zu öffnen.
Klicken Sie auf der Seite "Umgebungseinstellungen" auf "Webhook protokollieren ".
1. Wenn Sie die klassische Funktionalität verwenden, öffnen Sie die Seite Assistenten.
2. Klicken Sie für den Assistenten, den Sie konfigurieren möchten, auf das Symbol und wählen Sie dann Einstellungen aus.
3. Klicken Sie auf Webhooks und anschließend auf Webhook protokollieren.
Setzen Sie den Schalter Protokoll-Webhook auf Aktiviert.

Wenn Sie den Webhook nicht aktivieren können, müssen Sie möglicherweise Ihren Serviceplan upgraden.
Fügen Sie im Feld URL die URL für die externe Anwendung hinzu, an die Sie HTTP-POST-Anforderungsaufrufe senden wollen. Beispiel: https://example.com/my_log_service.

Sie müssen eine URL angeben, die das SSL-Protokoll verwendet. Geben Sie daher eine URL an, die mit https beginnt.
Fügen Sie im Feld Geheimer Schlüssel ein Token hinzu, das mit der Anforderung übergeben werden soll und für die Authentifizierung beim externen Service verwendet werden kann.

Der geheime Schlüssel muss als Zeichenfolge angegeben werden, z. B. purple unicorn. Die maximal zulässige Länge beträgt 1.024 Zeichen. Sie können keine Kontextvariablen angeben.

Es liegt in der Verantwortung des externen Service, den geheimen Schlüssel zu überprüfen und zu verifizieren. Wenn der externe Dienst kein Token erfordert, geben Sie eine beliebige Zeichenfolge an. Sie können dieses Feld nicht leer lassen.

Wenn Sie den geheimen Schlüssel bei der Eingabe anzeigen wollen, klicken Sie auf das Symbol Kennwort anzeigen , bevor Sie mit der Eingabe beginnen. Nach dem Speichern des geheimen Schlüssels wird die Zeichenfolge durch Sterne ersetzt und kann nicht erneut angezeigt werden.
Klicken Sie auf die entsprechenden Kontrollkästchen, um auszuwählen, welche Arten von Aktivitäten Sie protokollieren wollen.
- Wählen Sie Dialogprotokolle abonnieren aus, um Nachrichten und Antworten zu protokollieren.
- Um CDR-Ereignisse für die Telefonintegration zu protokollieren, wählen Sie CDR abonnieren aus.
Fügen Sie im Abschnitt 'Header' alle Header, die Sie an den Service übergeben wollen, jeweils einzeln durch Klicken auf Header hinzufügen hinzu.

Der Service sendet automatisch einen Authorization-Header mit einem JWT. Sie müssen keinen hinzufügen. Wenn Sie die Autorisierung selbst vornehmen möchten, fügen Sie Ihren eigenen Autorisierungsheader hinzu, der stattdessen verwendet wird.

Nach dem Speichern des Headerwerts wird die Zeichenfolge durch Sterne ersetzt und kann nicht erneut angezeigt werden.

Die Details Ihres Webhooks werden automatisch gespeichert.

Webhook entfernen

Wenn Sie Nachrichten nicht mit einem Webhook protokollieren wollen, führen Sie die folgenden Schritte aus:

Wechseln Sie in Ihrem Assistenten zu Umgebungen und öffnen Sie die Umgebung, in der Sie den Webhook konfigurieren wollen.
Klicken Sie auf das Symbol , um die Umgebungseinstellungen zu öffnen.
Klicken Sie auf der Seite "Umgebungseinstellungen" auf "Webhook protokollieren ".
1. Wenn Sie die klassische Funktionalität verwenden, öffnen Sie die Seite Assistenten.
2. Klicken Sie für den Assistenten, den Sie konfigurieren möchten, auf das Symbol und wählen Sie dann Einstellungen aus.
3. Klicken Sie auf Webhooks und anschließend auf Webhook protokollieren.
Führen Sie eine der folgenden Aktionen aus:
- Um den Webhook zu ändern, den Sie aufrufen möchten, klicken Sie auf Webhook löschen, um die aktuell angegebene URL und den geheimen Schlüssel zu löschen. Sie können dann URL und weitere Details hinzufügen.
- Um das Aufrufen eines Webhooks zum Protokollieren aller Nachrichten und Antworten zu stoppen, klicken Sie auf den Schalter Protokoll-Webhook, um den Webhook vollständig zu deaktivieren.

Webhook-Sicherheit

Um die Webhook-Anforderung zu authentifizieren, überprüfen Sie das JSON Web Token (JWT), das mit der Anforderung gesendet wird. Der Webhook-Mikroservice generiert automatisch ein JWT und sendet es mit jedem Webhook-Aufruf im Authorization-Header. Es liegt in Ihrer Verantwortung, Code zum externen Service hinzuzufügen, der das JWT überprüft.

Wenn Sie beispielsweise purple unicorn im Feld Geheimer Schlüssel angeben, können Sie Code wie den folgenden hinzufügen:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Hauptteil der Webhook-Anforderung

Der Anfragetext, den der Webhook an den externen Dienst sendet, ist ein JSON-Objekt mit folgender Struktur:

{
  "event": {
    "name": "{event_type}"
   },
  "payload": {
    ...
  }
}

Dabei ist {event_type} entweder message_logged (für Nachrichten und Antworten) oder cdr_logged (für CDR-Ereignisse).

Das Objekt payload enthält die zu protokollierenden Ereignisdaten. Die Struktur des Objekts payload hängt vom Ereignistyp ab.

Nutzdaten von Nachrichtenereignissen

Bei message_logged-Ereignissen enthält das payload-Objekt Daten zu einer Nachrichtenanforderung, die an den Assistenten gesendet wird, und zur Nachrichtenantwort, die an die Integrations- oder Clientanwendung zurückgegeben wird. Weitere Informationen zu den Feldern, die Teil von Nachrichtenanforderungen und -antworten sind, finden Sie in der API-Referenz.

Die Nutzdaten des Protokoll-Webhooks enthalten möglicherweise Daten, die derzeit von der API nicht unterstützt werden. Alle Felder, die nicht in der API-Referenzdokumentation definiert sind, können geändert werden.

Nutzdaten von CDR-Ereignissen

Für cdr_logged-Ereignisse enthält das Objekt payload Daten zu einem CDR-Ereignis (Call Detail Record), das von der Telefonintegration verarbeitet wurde. Die Struktur des Objekts payload für ein CDR-Ereignis sieht wie im folgenden Beispiel aus:

{
  "primary_phone_number": "+18005550123",
  "global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
  "failure_occurred": false,
  "transfer_occurred": false,
  "active_calls": 0,
  "warnings_and_errors": [
    {
      "code": "CWSMR0033W",
      "message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
    },
    {
      "code": "CWSMR0070W",
      "message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
    }
  ],
  "realtime_transport_network_summary": {
    "inbound_stream": {
      "average_jitter": 4,
      "canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
      "maximum_jitter": 18,
      "packets_lost": 0,
      "packets_transmitted": 952,
      "tool_name": ""
    },
    "outbound_stream": {
      "average_jitter": 0,
      "canonical_name": "voice.gateway",
      "maximum_jitter": 0,
      "packets_lost": 0,
      "packets_transmitted": 838,
      "tool_name": "IBM Voice Gateway/1.0.7.0"
    }
  },
  "call": {
    "start_timestamp": "2021-10-12T20:54:02.591Z",
    "stop_timestamp": "2021-10-12T20:54:20.375Z",
    "milliseconds_elapsed": 17784,
    "outbound": false,
    "end_reason": "assistant_hangup",
    "security": {
      "media_encrypted": false,
      "signaling_encrypted": false,
      "sip_authenticated": false
    }
  },
  "session_initiation_protocol": {
    "invite_arrival_time": "2021-10-12T20:54:00.565Z",
    "setup_milliseconds": 2026,
    "headers": {
      "call_id": "17465345_115257202@10.90.150.99",
      "from_uri": "sip:+18885550456@pstn.twilio.com",
      "to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
    }
  },
  "max_response_milliseconds": {
    "assistant": 339,
    "text_to_speech": 535,
    "speech_to_text": 0
  },
  "assistant_interaction_summaries": [
    {
      "session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
      "assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
      "turns": [
        {
          "assistant": {
            "log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
            "response_milliseconds": 339,
            "start_timestamp": "2021-10-12T20:54:00.722Z"
          },
          "request": {
            "type": "start"
          },
          "response": [
            {
              "barge_in_occurred": true,
              "streaming_statistics": {
                "response_milliseconds": 301,
                "start_timestamp": "2021-10-12T20:54:00.722Z",
                "stop_timestamp": "2021-10-12T20:54:01.023Z",
                "transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
              },
              "type": "text_to_speech"
            }
          ]
        },
        {
          "assistant": {
            "log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
            "response_milliseconds": 158,
            "start_timestamp": "2021-10-12T20:54:05.621Z"
          },
          "request": {
            "type": "dtmf"
          },
          "response": [
            {
              "type": "disable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": false,
              "streaming_statistics": {
                "transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
                "start_timestamp": "2021-10-12T20:54:06.321Z",
                "stop_timestamp": "2021-10-12T20:54:14.338Z",
                "response_milliseconds": 535
              }
            },
            {
              "type": "enable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": true,
              "streaming_statistics": {
                "transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
                "start_timestamp": "2021-10-12T20:54:14.795Z",
                "stop_timestamp": "2021-10-12T20:54:20.388Z",
                "response_milliseconds": 447
              }
            }
          ]
        },
        {
          "assistant": {
            "log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
            "response_milliseconds": 0,
            "start_timestamp": "2021-10-12T20:54:20.377Z"
          },
          "request": {
            "type": "hangup"
          },
          "response": []
        }
      ]
    }
  ]
}

Weitere Informationen zur Struktur der CDR-Ereignisnutzlast finden Sie unter CDR-Protokollereignisreferenz.