Aufruf eines Dienstes nach der Verarbeitung einer Nachricht für watsonx Orchestrate

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 Postmessage-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 Nachbearbeitung.

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

Beispiel: Sie speichern die Antworten Ihres Assistenten in einem separaten Content-Management-System. Wenn der Assistent die Eingabe versteht, gibt die verarbeitete Aktion eine eindeutige ID zurück, die einer Antwort in Ihrem CMS entspricht. Um einen Service aufzurufen, der eine Antwort von Ihrem CMS für eine bestimmte eindeutige ID abruft, geben Sie die URL für Ihre Serviceinstanz an. Beispiel: https://example.com/get_answer.

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

1. Um die Authentifizierung für Post-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.

2. 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.

3. 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.

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

2. Die Details Ihres Webhooks werden automatisch gespeichert.

Konfiguration der Fehlerbehandlung bei Webhooks für die Nachbearbeitung

Sie können entscheiden, ob im Nachbearbeitungsschritt 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 die Fehler und verarbeitet die Nachricht ohne das Webhook-Ergebnis. Wenn eine Nachbearbeitung nützlich, aber nicht unbedingt erforderlich ist, sollten Sie diese Option in Betracht ziehen.

• Einen Fehler an den Client zurückgeben, wenn der Webhook-Aufruf fehlschlägt : Wenn die Nachbearbeitung nach dem Senden einer Antwort durch den Assistenten wichtig ist, wählen Sie diese Option.

Wichtig: Wenn Sie die Option „Fehler an den Client zurückgeben, falls der Webhook-Aufruf fehlschlägt“ aktivieren, wird der gesamte Prozess angehalten, bis der Nachbearbeitungsschritt erfolgreich abgeschlossen ist.

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

Webhook testen

Wichtig: Testen Sie Ihren Webhook gründlich, bevor Sie ihn für einen Assistenten aktivieren, der in einer Produktionsumgebung eingesetzt wird.

Der Webhook wird nur ausgelöst, wenn Ihr Assistent eine Nachricht verarbeitet und eine Antwort bereit ist, an den Kanal zurückgegeben zu werden.

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 Webhook-Bodys nach der Anfrage zu kennen, damit Ihr externer Code ihn verarbeiten kann.

Die Nutzlast enthält den Antwortkörper, den Ihr Assistent für den API-Aufruf der Version 2 /message zurückgibt, sowohl für zustandsabhängige als auch für zustandslose API-Aufrufe. Der Ereignisname message_processed zeigt an, dass der Post-Message-Webhook die Anfrage erzeugt. Weitere Informationen zum Hauptteil der Nachrichtenanfrage finden Sie in der API-Referenz.

Das folgende Beispiel zeigt, wie ein einfacher Anfragetext formatiert ist:

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

Beispiel 1

Dieses Beispiel zeigt, wie man y'all am Ende jeder Antwort des Assistenten hinzufügt.

Auf der Konfigurationsseite für den Post-Message-Webhook werden die folgenden Werte angegeben:

• URL: https://your-webhook-url/

• Headername: Inhaltstyp

• Headerwert: application/json

Der Post-Message-Webhook ruft eine IBM Cloud Functions Web-Aktion namens add_southern_charm auf.

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

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return { 
        body : params
    }
  }
}

Beispiel 2

Dieses Beispiel zeigt, wie man eine Antwort auf eine Nachricht in die Sprache des Kunden zurückübersetzt. Es funktioniert nur, wenn Sie die Schritte in Beispiel 2 ausführen, um einen Webhook vor der Nachricht zu definieren, der die Originalnachricht ins Englische übersetzt.

Definieren Sie eine Folge von Webaktionen in IBM Cloud Functions. Die erste Aktion in der Sequenz prüft die Sprache des ursprünglich eingehenden Textes, die Sie in einer Kontextvariablen namens original_input im Webhook-Code vor der Nachricht gespeichert haben. Die zweite Aktion in der Sequenz übersetzt den Dialogantworttext aus Englisch in die Originalsprache, die vom Kunden verwendet wurde.

Auf der Konfigurationsseite für den Post-Message-Webhook werden die folgenden Werte angegeben:

• URL: https://your-webhook-url/

• 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.output.generic[0].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': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  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 param
}
};

Die zweite Webaktion in der Sequenz sieht wie folgt aus:

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

function main(params) {
  console.log(JSON.stringify(params))
    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'
        },
    body: { 
        text: [ 
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true 
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return { 
    body : params
  }
};

Webhook entfernen

Wenn Sie keine Nachrichtenantworten mit einem Webhook verarbeiten 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 Post-Message-Webhook.

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

   • Um einen Webhook nicht mehr zur Verarbeitung jeder eingehenden Nachricht aufzurufen, setzen Sie den Schalter Post-message webhook auf Disabled.

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