Protokollierung von Aktivitäten mit einem Webhook
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, den Sie verwenden können, um ein externes Programm auf der Grundlage von Ereignissen in Ihrem Programm aufzurufen.
Diese Funktion ist nur für Nutzer der Plus- und Enterprise-Tarife verfügbar. Der Plus-Plan erlaubt maximal 5 Log-Webhooks pro Instanz. Dieses Limit gilt nicht für die Instanzen des Enterprise-Plans.
Fügen Sie Ihrem Assistenten einen Log-Webhook hinzu, wenn Sie einen externen Dienst zur Protokollierung von Aktivitäten nutzen möchten. Sie können zwei Arten von Aktivitäten protokollieren:
Meldungen und Antworten: Der Log-Webhook wird jedes Mal ausgelöst, wenn der Assistent auf eine Kundeneingabe antwortet. 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 v2 ' /message API (zustandslos und zustandsabhängig). Weitere Informationen finden Sie in der API-Referenz. Alle integrierten Kanalintegrationen verwenden diese API.
Anrufdatensätze (CDRs): Der Log-Webhook wird nach jedem Telefonat ausgelöst, das ein Benutzer mit Ihrem Assistenten führt, der die Telefonintegration nutzt. 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-Datensätze sind nur für Assistenten, die die Telefonintegration nutzen.
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.
Klicken Sie für den Assistenten, den Sie konfigurieren möchten, auf das
Symbol und wählen Sie dann „Einstellungen “.Klicken Sie auf Webhaken und dann auf Webhaken 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. Zum 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 für den externen Dienst kein Token erforderlich ist, können Sie eine beliebige Zeichenfolge angeben. Sie können dieses Feld nicht leer lassen.
Wenn Sie das Passwort während der Eingabe sehen möchten, klicken Sie auf das Symbol „Passwort 
anzeigen“, bevor Sie mit der Eingabe beginnen. Nachdem Sie das Geheimnis gespeichert haben, wird die Zeichenfolge durch Sternchen ersetzt und kann nicht mehr eingesehen 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 einen eigenen Autorisierungskopf hinzu, der stattdessen verwendet wird.
Nachdem Sie den Wert der Kopfzeile gespeichert haben, wird die Zeichenfolge durch Sternchen ersetzt und kann nicht mehr 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:
Gehen Sie in Ihrem Assistenten auf Umgebungen und öffnen Sie 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.
Klicken Sie für den Assistenten, den Sie konfigurieren möchten, auf das
Symbol und wählen Sie dann „Einstellungen “.Klicken Sie auf Webhaken und dann auf Webhaken 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 eine URL und andere 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 zum Beispiel " purple unicorn in das Feld "Secret" eingeben, können Sie einen 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 Anfragekörper, den der Webhook an den externen Dienst sendet, ist ein JSON-Objekt mit der folgenden 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 enthält das " payload Daten über eine an den Assistenten gesendete Nachrichtenanforderung und die an die Integrations- oder Client-Anwendung zurückgesendete Nachrichtenantwort. 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 über die Struktur der CDR-Ereignis-Payload finden Sie unter CDR-Log-Ereignisreferenz.