Webhook-Konfiguration

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

1. Klicken Sie im Navigationsbereich auf Umgebungen und öffnen Sie die Umgebung, in der Sie den Webhook konfigurieren möchten.

2. Klicken Sie auf das Symbol , um die Umgebungseinstellungen zu öffnen.

3. Setzen Sie den Schalter Premessage-Webhook auf Aktiviert.

4. Wählen Sie im Ereignis Synchronous eine der folgenden Optionen aus:

   • Verarbeitung der Benutzereingabe ohne Webhook-Aktualisierung fortsetzen, wenn ein Fehler auftritt.

   • Gibt einen Fehler an den Client zurück, wenn der Webhook-Aufruf fehlschlägt.

   Weitere Informationen finden Sie unter Konfigurieren der Webhook-Fehlerbehandlung für die Vorverarbeitung.

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

   Sie könnten z. B. eine Cloud Functions Web-Aktion schreiben, die prüft, ob eine Nachricht in einer anderen Sprache als Englisch vorliegt, und sie an den Dienst Language Translator senden, um sie ins Englische zu konvertieren. Geben Sie die URL für Ihre Webaktion wie im folgenden Beispiel an:

   https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
   

   Sie müssen eine URL angeben, die das SSL-Protokoll verwendet. Geben Sie daher eine URL an, die mit https beginnt.

6. Um die Authentifizierung für Pre-Message-Webhooks zu konfigurieren, klicken Sie auf Authentifizierung bearbeiten. Detaillierte Anweisungen finden Sie unter Definieren der Authentifizierungsmethode für Pre-Message- und Post-Message-Webhooks.

7. Geben Sie im Feld Timeout die Zeitdauer in Sekunden an, die der Assistent auf eine Antwort vom Webhook warten soll, bevor er einen Fehler zurückgibt. Das Zeitlimit kann nicht kürzer als 1 Sekunde oder länger als 30 Sekunden sein.

8. Klicken Sie im Abschnitt Kopfzeilen auf Kopfzeile hinzufügen +, um die Kopfzeilen, die Sie an den Dienst übergeben möchten, einzeln hinzuzufügen.

   Wenn die externe Anwendung, die Sie aufrufen, eine Antwort zurücksendet, kann sie möglicherweise eine Antwort in verschiedenen Formaten senden. Der Webhook erfordert, dass die Antwort in JSON formatiert ist. Die folgende Tabelle veranschaulicht, wie Sie eine Kopfzeile hinzufügen, um anzugeben, dass der Ergebniswert im JSON-Format zurückgegeben werden soll.

   Beispiel für einen Header

   Headername	Headerwert
   Content-Type	application/json

9. Nachdem Sie den Wert der Kopfzeile gespeichert haben, wird die Zeichenfolge durch Sternchen ersetzt und kann nicht mehr angezeigt werden.

10. Die Details Ihres Webhooks werden automatisch gespeichert.

Konfigurieren der Webhook-Fehlerbehandlung für die Vorverarbeitung

Sie können entscheiden, ob im Vorverarbeitungsschritt ein Fehler zurückgegeben wird, wenn der Webhook-Aufruf fehlschlägt. Es stehen zwei Optionen zur Auswahl:

• Verarbeitung der Benutzereingabe ohne Webhook-Aktualisierung fortsetzen, wenn ein Fehler auftritt: Der Assistent ignoriert Fehler und verarbeitet die Nachricht ohne das Webhook-Ergebnis. Wenn die Vorverarbeitung nützlich, aber nicht unbedingt erforderlich ist, sollten Sie diese Option in Betracht ziehen.

• Gibt einen Fehler an den Client zurück, wenn der Webhook-Aufruf fehlschlägt: Wenn die Vorverarbeitung entscheidend ist, bevor der Assistent eine Nachricht verarbeitet, wählen Sie diese Option.

Wenn Sie „Bei fehlgeschlagenem Webhook-Aufruf einen Fehler an den Client zurückgeben“ aktivieren, wird alles angehalten, bis der Vorverarbeitungsschritt erfolgreich abgeschlossen wurde.

Testen Sie den externen Prozess regelmäßig, um mögliche Fehler zu erkennen. Passen Sie diese Einstellung gegebenenfalls an, um Unterbrechungen bei der Nachrichtenverarbeitung zu vermeiden.

Webhook testen

Testen Sie Ihren Webhook ausführlich, bevor Sie ihn für einen Assistenten aktivieren, der in einer Produktionsumgebung verwendet wird.

Der Webhook wird ausgelöst, wenn eine Nachricht zur Verarbeitung an Ihren Assistenten gesendet wird.

Fehlerbehebung für den Webhook

Die folgenden Fehlercodes können Ihnen dabei helfen, die Ursache von Problemen zu ermitteln, die möglicherweise auftreten. Wenn Sie z. B. eine Web-Chat-Integration haben, wissen Sie, dass Ihr Webhook ein Problem hat, wenn jede Testnachricht, die Sie senden, eine Nachricht wie There is an error with the message you just sent, but feel free to ask me something else zurückgibt. Wenn diese Meldung angezeigt wird, verwenden Sie ein REST-API-Tool, wie z. B. cURL,, um eine Test-API-Anforderung an /message zu senden, damit Sie den Fehlercode und die vollständige Meldung, die zurückgegeben wird, sehen können.

Beispiel für Anforderungshauptteil

Es ist nützlich, das Format des Anfragekörpers des Pre-Message-Webhooks zu kennen, damit Ihr externer Code ihn verarbeiten kann.

Der Payload enthält den Request Body der /message, stateful oder stateless, Version 2 der API-Anfrage. Der Ereignisname message_received zeigt an, dass die Anfrage durch den Pre-Message-Webhook generiert wird. Weitere Informationen über den Nachrichtentext finden Sie in der API-Referenz.

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

Überspringen der Assistentenverarbeitung

Verbesserungen an Pre-Message-Webhooks ermöglichen es Cloud Pak for Data, die Nachrichtenverarbeitung zu überspringen und direkt die Antwort des Webhooks zurückzugeben. Diese Funktion wird durch Setzen der Kopfzeile x-watson-assistant-webhook-return in der Antwort des Webhooks HTTP aktiviert.

Antworthauptteil

Der Service, der die POST-Anforderung vom Webhook empfängt, muss ein JSON-Objekt (Accept: application/json) zurückgeben.

Der Antworthauptteil muss die folgende Struktur aufweisen:

{
  "payload": {
    ...
  }
}

Die Antwort payload muss die payload aus dem Anfragetext enthalten. Ihr Code kann Eigenschaftswerte oder Kontextvariablen ändern, aber die zurückgegebene Nutzlast der Nachricht muss dem Schema der Methode message entsprechen. Weitere Informationen finden Sie in der API-Referenz.

Beispiel 1

Dieses Beispiel zeigt Ihnen, wie Sie die Sprache des Eingabetextes überprüfen und die Sprachinformationen an die Eingabetextzeichenfolge anhängen können.

Auf der Webhook-Konfigurationsseite für die Vorabmeldung werden die folgenden Werte angegeben:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• Headername: Inhaltstyp
• Headerwert: application/json

Der Pre-Message-Webhook ruft eine IBM Cloud Functions Web-Aktion namens check_language auf.

Der node.js-Code in der check_language-Webaktion sieht wie folgt aus:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input text.
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return {
    body : params
}
};

Klicken Sie zum Testen des Webhooks auf Vorschau. Senden Sie den Text Buenos días. Der Assistent kann die Eingabe wahrscheinlich nicht verstehen und gibt die Antwort von Ihrem Anything else-Knoten zurück. Wenn Sie jedoch die Analyseseite Ihres Assistenten aufrufen und Konversationen öffnen, können Sie sehen, was übermittelt wurde. Überprüfen Sie die letzte Benutzerkonversation. Das Protokoll zeigt, dass die Benutzereingabe Buenos días (in es) lautet. Die es in Klammern steht für den Sprachcode für Spanisch, so dass der Webhook funktionierte und erkannte, dass der übermittelte Text ein spanischer Satz war.

Beispiel 2

Dieses Beispiel zeigt Ihnen, wie Sie die Sprache der eingehenden Nachricht überprüfen und, falls sie nicht Englisch ist, ins Englische übersetzen, bevor Sie sie an den Assistenten weiterleiten.

Definieren Sie eine Folge von Webaktionen in IBM Cloud Functions. Die erste Aktion in der Sequenz überprüft die Sprache des eingehenden Texts. Die zweite Aktion in der Sequenz übersetzt den Text aus seiner ursprünglichen Sprache in Englisch.

Auf der Webhook-Konfigurationsseite für die Vorabmeldung werden die folgenden Werte angegeben:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• Headername: Inhaltstyp
• Headerwert: application/json

Der node.js-Code für die erste Webaktion in Ihrer Sequenz sieht wie folgt aus:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills["actions skill"].user_defined["language"] = 'none'
    return params
}
};

Die zweite Webaktion in der Sequenz sendet den Text an den Watson Language Translator-Service, um den Eingabetext aus der Sprache, die in der vorherigen Webaktion angegeben wurde, ins Englische zu übersetzen. Die übersetzte Zeichenfolge wird dann anstelle des ursprünglichen Textes an Ihren Assistenten gesendet.

Der node.js-Code für die zweite Aktion in Ihrer Sequenz sieht wie folgt aus:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: {
      text: [
          params.payload.input.text
          ],
          target: 'en'
  },
  json: true
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return {
    body : params
    }
};

Wenn Sie den Webhook in der Vorschauanzeige testen, können Sie Buenos días abschicken und der Assistent antwortet, als ob Sie Good morning auf Englisch gesagt haben. Wenn Sie die Analyseseite Ihres Assistenten aufrufen und Konversationen öffnen, zeigt das Protokoll, dass die Benutzereingabe Good morning war.

Sie können einen Post-Message-Webhook hinzufügen, um die Antwort auf die Nachricht wieder in die Sprache des Kunden zu übersetzen, bevor sie angezeigt wird. Für weitere Informationen siehe Beispiel 2.

Beispiel 3

Dieses Beispiel zeigt, wie man eine Webhook-Antwort so zusammenstellt, dass Cloud Pak for Data die Verarbeitung der Nachricht überspringt und direkt die Antwort des Webhooks zurückgibt.

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

Webhook entfernen

Wenn Sie die Kundeneingabe nicht mit einem Webhook vorverarbeiten möchten, führen Sie die folgenden Schritte aus:

1. Gehen Sie in Ihrem Assistenten auf Umgebungen und öffnen Sie die Umgebung, in der Sie den Webhook entfernen möchten.

2. Klicken Sie auf das Symbol , um die Umgebungseinstellungen zu öffnen.

3. Klicken Sie auf der Seite Umgebungseinstellungen auf Webhaken für Vorabnachrichten.

4. Führen Sie einen der folgenden Schritte aus:

• Wenn Sie keinen Webhook mehr aufrufen möchten, um jede eingehende Nachricht zu verarbeiten, setzen Sie den Webhook-Schalter für die Vorabmeldung auf Deaktiviert.

• Um den aufzurufenden Webhook zu ändern, klicken Sie auf Webhook löschen.