Webhook definieren

Sie können URL für einen Dialog definieren und den Webhook dann von einem oder mehreren Dialogknoten aus aufrufen.

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

• Der Aufruf muss eine HTTP-Anforderung POST sein.
• Der Anforderungshauptteil muss ein JSON-Objekt (Content-Type: application/json) sein.
• Die Antwort muss ein JSON-Objekt (Accept: application/json) sein.
• Der Anruf muss innerhalb von 8 Sekunden oder weniger beantwortet werden. Wenn der Aufruf mehrmals in einem einzelnen Nachrichtenaufruf über Dialogmodulknoten gestartet wird, müssen alle diese Aufrufe in maximal 8 Sekunden zurückgegeben werden.

Wenn Ihr externer Dienst nur GET-Anfragen unterstützt oder wenn Sie URL zur Laufzeit dynamisch angeben müssen, sollten Sie die Erstellung eines Zwischendienstes in Betracht ziehen, der eine POST-Anfrage mit einer JSON-Nutzlast akzeptiert, die beliebige Laufzeitwerte enthält. Der temporäre Service kann dann eine Anforderung an den Zielservice absetzen, diese Werte als URL-Parameter übergeben und dann die Antwort an den Dialog zurückgeben.

Wenn Sie einen Service aufrufen müssen, der möglicherweise nicht innerhalb von acht Sekunden zurückgegeben wird, können Sie den Aufruf über eine angepasste Clientanwendung verwalten und die Informationen als separaten Schritt an den Dialog übergeben. Weitere Informationen finden Sie unter Clientaktionen anfordern.

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

1. Klicken Sie in dem Dialog, in dem Sie den Webhook hinzufügen wollen, auf Webhooks.

2. Fügen Sie im Feld URL die URL für die externe Anwendung hinzu, an die Sie HTTP-POST-Anforderungsaufrufe senden wollen.

   Um beispielsweise Language Translator aufzurufen, geben Sie URL für Ihre Dienstinstanz an.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   Wenn die externe Anwendung, die Sie aufrufen, eine Antwort zurückgibt, muss sie eine Antwort im JSON-Format zurücksenden können. Für Language Translator müssen Sie beispielsweise das Format angeben, in dem das Ergebnis zurückgegeben werden soll. Sie können dies tun, indem Sie einen Header an den Service übergeben.

3. Fügen Sie im Abschnitt 'Header' alle Header, die Sie an den Service übergeben wollen, jeweils einzeln durch Klicken auf Header hinzufügen hinzu.

   Dieser Header gibt beispielsweise an, dass die Anforderung im JSON-Format vorliegt.

   Beispiel für einen Header

   Headername	Headerwert
   Content-Type	application/json

4. Wenn ein externer Service voraussetzt, dass Berechtigungsnachweise für eine Basisauthentifizierung mit der Anforderung übergeben werden, geben Sie diese an. Klicken Sie auf Autorisierung hinzufügen, fügen Sie Ihre Berechtigungsnachweise in den Feldern Benutzername und Kennwort hinzu und klicken Sie auf Speichern.

   Das Produkt erstellt eine ASCII-Zeichenfolge in Base64-Codierung aus den Berechtigungsnachweisen und generiert einen Header, der zur Seite hinzugefügt wird.

   Beispiel für einen Header

   Headername	Headerwert
   Autorisierung	Basic <encoded-credentials>

   Wenn Sie die Web-Chat-Integration verwenden und die Sicherheit aktivieren, können Sie dasselbe Token verwenden, das Sie zur Sicherung des Web-Chats im Autorisierungsheader verwenden. Weitere Informationen finden Sie in Web-Chat: JSON-Web-Token (JWT) zur Webhook-Authentifizierung verwenden.

Die Details Ihres Webhooks werden automatisch gespeichert.

Webhookaufruf in einem Dialogmodulknoten hinzufügen

Zur Verwendung eines Webhooks in einem Dialogmodulknoten müssen Sie Webhooks in dem Knoten aktivieren und anschließend Details für den Aufruf (Callout) hinzufügen.

1. Suchen Sie den Dialogmodulknoten, in dem Sie einen Aufruf hinzufügen wollen. Der Aufruf des Webhooks erfolgt immer dann, wenn dieser Knoten während einer Konversation mit einem Benutzer ausgelöst wird.

   Sie könnten zum Beispiel einen Aufruf vom Knoten #General_Greetings an den Webhook senden.

2. Klicken Sie, um den Dialogmodulknoten zu öffnen, und klicken Sie auf Anpassen.

3. Blättern Sie zum Abschnitt für Webhooks nach unten. Stellen Sie den Schalter "Call out to webhooks/actions" auf "On ".

4. Wählen Sie Webhook aufrufen aus und klicken Sie auf Anwenden.

   Wenn Sie diese Einstellung nicht bereits aktiviert haben, wird der Schalter Mehrere bedingte Antworten automatisch auf Ein gesetzt, und Sie können diese Einstellung nicht inaktivieren. Diese Einstellung wird aktiviert, um das Hinzufügen verschiedener Antworten abhängig von Fehler oder Erfolg des Webhookaufrufs zu unterstützen. Wenn Sie eine Antwort haben, die bereits für den Knoten angegeben ist, wird sie zur ersten bedingten Antwort.

5. Fügen Sie alle Daten, die an die externe Anwendung übergeben werden sollen, in Form von Schlüssel/Wert-Paaren im Abschnitt Parameter hinzu.

   Parameter werden als Eigenschaften des Anforderungshauptteils übergeben. Sie können keine Abfrageparameter oder URL-Parameter in einem Dialogmodulknoten angeben. Diese Parameter können im Rahmen der Webhook-Definition nur mit statischen Werten konfiguriert werden. Weitere Informationen finden Sie in Webhook definieren.

   Wenn Sie zum Beispiel den Language Translator-Service aufrufen, müssen Sie Werte für die folgenden Parameter angeben:

   Beispiel für Parameter

   Schlüssel	Wert	Beschreibung
   model_id	en-es	Gibt die Ein- und Ausgabesprache an. In diesem Beispiel wird durch die Anforderung eine Übersetzung von Text aus dem Englischen (en) in das Spanische (es) angegeben.
   Text	How are you?	Dieser Parameter enthält die Textzeichenfolge, die der Service übersetzen soll. Sie können diesen Wert fest codieren, eine Kontextvariable wie $saved_text übergeben oder die Benutzereingabe direkt an den Dienst weitergeben, indem Sie <? input.text ?> als diesen Wert angeben.

   In komplexeren Fällen können Sie zum Beispiel Informationen während des Dialogs mit einem Benutzer zu seinen Reiseplänen erfassen. Sie können Datumsangaben und Reisezielinformationen erfassen und in Kontextvariablen speichern, die Sie als Parameter an eine externe Anwendung übergeben können.

   Beispiel für Reiseparameter

   Schlüssel	Wert
   depart_date	$departure
   arrive_date	$arrival
   Ursprung	$origin
   destination	$destination

6. Jede Antwort, die durch den Aufruf erfolgt, wird in der Rückgabevariablen gespeichert. Sie können die Variable, die dem Feld Rückgabevariable automatisch hinzufügt wird, umbenennen. Wenn der Aufruf einen Fehler zur Folge hat, wird diese Variable auf den Wert null gesetzt.

   Der generierte Variablenname hat die Syntax webhook_result_n, wobei das Suffix _n jedes Mal erhöht wird, wenn Sie einem Dialogknoten eine Webhook-Callout-Funktion hinzufügen. Diese Namenskonvention stellt sicher, dass die Namen der Kontextvariablen im gesamten Dialog eindeutig sind. Falls Sie den Namen ändern, müssen Sie sicherstellen, dass Sie einen eindeutigen Namen verwenden.

7. Im Abschnitt für bedingte Antworten werden automatisch zwei Antwortbedingungen hinzugefügt. Die eine Bedingung gilt für eine Antwort, die angezeigt wird, wenn der Webhookaufruf erfolgreich ist und eine Rückgabevariable zurückgesendet wird. Die andere Bedingung gilt für eine Antwort, die angezeigt wird, wenn der Aufruf fehlschlägt. Sie können diese Antworten bearbeiten und dem Knoten weitere bedingte Antworten hinzufügen.

   • Wenn der Aufruf eine Antwort zurückgibt und Sie das Format der JSON-Antwort kennen, können Sie die Antwort des Dialogmodulknotens bearbeiten, um nur den Abschnitt der Antwort hinzuzufügen, den Sie mit Benutzern teilen möchten.

     Zum Beispiel gibt der Language Translator-Service ein Objekt wie das folgende zurück:

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     Verwenden Sie einen SpEL-Ausdruck, der nur den übersetzten Textwert extrahiert.

     Beispiel für bedingte Antworten

     Bedingung	Antwort
     $webhook_result_1	Ihre Worte auf Spanisch:
     anything_else	Der Aufruf der externen Anwendung ist fehlgeschlagen. Wiederholen Sie die Operation zu einem späteren Zeitpunkt.

     Wenn Sie das empfohlene Format für die Antwort verwenden und die zuvor angezeigte Antwort in der Übersetzung zurückgegeben wird, lautet die Antwort des Assistenten an den Benutzer: Your words in Spanish: ¿Cómo estás?

   • Wenn Sie eine bestimmte Antwort bereitstellen möchten, wenn die Callout-Funktion eine leere Zeichenfolge zurückgibt, was bedeutet, dass der Aufruf erfolgreich ist, der zurückgegebene Wert jedoch eine leere Zeichenfolge ist, können Sie eine bedingte Antwort hinzufügen, die eine Bedingung mit einer Syntax wie dieser hat:

     $webhook_result_1.size() == 0
     

8. Wenn Sie Ihre Bearbeitung abgeschlossen haben, klicken Sie auf das X, um den Knoten zu schließen. Ihre Änderungen werden automatisch gespeichert.

Webhooks testen

Wenn Sie zum ersten Mal eine Webhook-Callout hinzufügen, kann es nützlich sein, genau zu sehen, was in der Antwort von der externen Anwendung zurückgegeben wird, die Daten und ihr Format. Fügen Sie diesen Ausdruck als Textantwort für die erfolgreiche bedingte Callout-Antwort hinzu: $webhook_result_n, wobei n die entsprechende Nummer für den Webhook ist, den Sie testen.

Diese Antwort gibt den vollständigen Hauptteil der Rückgabevariablen zurück, sodass Sie sehen können, welche Informationen der Aufruf zurücksendet, und entscheiden können, welche davon mit dem Benutzer geteilt werden sollen. Sie können dann die in den Methoden der Expression-Sprache dokumentierten Methoden verwenden, um nur die Informationen aus der Antwort zu extrahieren, die Sie interessieren.

Testen Sie, ob bestimmte Benutzereingaben Fehler in dem Aufruf generieren können, und entwickeln Sie Verfahren zur Behandlung solcher Situationen. Fehler, die von der externen Anwendung generiert werden, werden in output.webhook_error.<result_variable> gespeichert. Sie können während der Tests eine bedingte Antwort wie die folgende verwenden, um solche Fehler zu erfassen:

Sie führen zum Beispiel keine ordnungsgemäße Authentifizierung der Anforderung durch (401) oder Sie versuchen, einen Parameter mit einem Namen zu übergeben, der von der externen Anwendung bereits verwendet wird. Testen Sie den Webhook, um solche Typen von Fehlern zu ermitteln und zu beheben, bevor Sie den Webhook bereitstellen.

Webhook entfernen

Wenn Sie entscheiden, dass kein Webhookaufruf aus einem Dialogmodulknoten heraus erfolgen soll, öffnen Sie die Seite Anpassen des Knotens und inaktivieren Sie den Schalter 'Webhooks' (Aus).

Der Abschnitt Parameter und das Feld Rückgabevariable werden aus dem Dialogmodulknoteneditor entfernt. Allerdings bleiben alle bedingten Antworten erhalten, die für Sie hinzugefügt wurden oder die Sie selbst hinzugefügt haben.

Der Abschnitt Mehrere bedingte Antworten ist erneut bearbeitbar. Sie können die Funktion auch ausschalten. Wenn Sie dies tun, wird nur die erste bedingte Antwort als einzige Textantwort des Knotens gespeichert.

Zum Ändern des externen Service, den Sie über Dialogmodulknoten aufrufen, bearbeiten Sie die Webhookdetails, die auf der Seite 'Webhooks' der Registerkarte Optionen definiert sind. Wenn der neue Service die Übergabe anderer Parameter erwartet, stellen Sie sicher, dass Sie alle Dialogmodulknoten aktualisieren, die ihn aufrufen.

output.generic mit einem Webhook aktualisieren

Sie können einen Webhook verwenden, um output.generic zu aktualisieren und dynamische Antworten bereitzustellen. Weitere Informationen finden Sie im Blogartikel How to Dynamically Add Response Options to Dialog Nodes.