Appel d'un service avant le traitement d'un message pour watsonx Orchestrate

Configuration de webhook

Pour ajouter les détails du webhook, procédez comme suit :

1. Dans le panneau de navigation, cliquez sur Environnements et ouvrez l'environnement dans lequel vous souhaitez configurer le webhook.

2. Cliquez sur l'icône pour ouvrir les paramètres de l'environnement.

3. Définissez le commutateur webhook de pré-message sur Activé.

4. Dans l' événement Synchrone, sélectionnez l'une des options suivantes :

   • Continuer à traiter les données de l'utilisateur sans mettre à jour le webhook en cas d'erreur.

   • Renvoyer une erreur au client si l'appel au webhook échoue.

Pour plus d'informations, voir Configuration de la gestion des erreurs des webhooks pour le prétraitement.

1. Dans la zone URL, ajoutez l'URL de l'application externe à laquelle vous souhaitez envoyer des appels de demande POST HTTP.

Par exemple, vous pouvez écrire une action web Cloud Functions qui vérifie si un message est dans une langue autre que l'anglais et l'envoie au service Language Translator pour le convertir en anglais. Indiquez l'URL de votre action Web, comme dans cet exemple :

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

Vous devez spécifier une URL qui utilise le protocole SSL, donc indiquez une URL commençant parhttps.

1. Pour configurer l'authentification pour les webhooks avant message, cliquez sur Modifier l'authentification. Pour des instructions détaillées, voir Définir la méthode d'authentification pour les webhooks pré-message et post-message.

2. Dans le champ Délai d'attente, indiquez la durée, en secondes, pendant laquelle l'assistant doit attendre une réponse du webhook avant de renvoyer une erreur. La durée du délai d'attente ne peut pas être inférieure à 1 seconde ou supérieure à 30 secondes.

3. Dans la section En-têtes, cliquez sur Ajouter un en-tête + pour ajouter les en-têtes que vous souhaitez transmettre au service, un par un.

Si l'application externe que vous appelez renvoie une réponse, elle peut être en mesure d'envoyer une réponse dans différents formats. Le webhook nécessite que la réponse soit formatée au format JSON. Le tableau suivant illustre comment ajouter un en-tête pour indiquer que vous souhaitez que la valeur résultante soit renvoyée au format JSON.

1. Après avoir enregistré la valeur de l'en-tête, la chaîne est remplacée par des astérisques et ne peut plus être consultée.

2. Les détails du webhook sont sauvegardés automatiquement.

Configuration de la gestion des erreurs des webhooks pour le prétraitement

Vous pouvez décider de renvoyer une erreur lors de l'étape de prétraitement si l'appel au webhook échoue. Deux options s'offrent à vous :

• Poursuivre le traitement des données de l'utilisateur sans mise à jour du webhook en cas d'erreur : L'assistant ignore les erreurs et traite le message sans le résultat du webhook. Si le prétraitement est utile mais pas essentiel, envisagez cette option.

• Renvoyer une erreur au client si l'appel au webhook échoue : Si le prétraitement est essentiel avant que l'assistant ne traite un message, sélectionnez cette option.

Important : lorsque vous activez l'option « Renvoyer une erreur au client en cas d'échec de l'appel du webhook », tout s'arrête jusqu'à ce que l'étape de post-traitement soit terminée avec succès.

Tester régulièrement le processus externe afin d'identifier les défaillances potentielles. Si nécessaire, ajuster ce paramètre pour éviter des perturbations dans le traitement des messages.

Test du webhook

Important : testez minutieusement votre webhook avant de l'activer pour un assistant utilisé en environnement de production.

Le webhook est déclenché lorsqu'un message est envoyé à votre assistant pour être traité.

Idenfication et traitement des incidents liés au webhook

Les codes d'erreur suivants peuvent vous aider à déterminer la cause des problèmes que vous pourriez rencontrer. Si vous avez une intégration de chat en ligne, par exemple, vous savez que votre webhook présente un problème si chaque message de test que vous envoyez renvoie un message tel que There is an error with the message you just sent, but feel free to ask me something else. Si ce message s'affiche, utilisez un outil API REST, tel que cURL,, pour envoyer une requête API /message de test, afin de voir le code d'erreur et le message complet qui est renvoyé.

Exemple de corps de demande

Il est utile de connaître le format du corps de la requête du webhook de pré-message afin que votre code externe puisse le traiter.

La charge utile contient le corps de la demande de /message, avec ou sans état, version 2 de la demande d'API. Le nom de l'événement message_received indique que la demande est générée par le webhook de pré-message. Pour plus d'informations sur le corps de la requête, consultez la documentation de l'API.

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

Ignorer le traitement par l'assistant

Les améliorations apportées aux webhooks de pré-message permettent à watsonx Orchestrate d'ignorer le traitement du message et de renvoyer directement la réponse depuis le webhook. Cette fonctionnalité est activée en définissant x-watson-assistant-webhook-return l'en-tête dans la réponse « HTTP » du webhook.

Corps de la réponse

Le service qui reçoit la requête POST du webhook doit renvoyer un objet JSON Accept: application/json).

Le corps de la réponse doit avoir la structure suivante :

{
  "payload": {
    ...
  }
}

La réponse payload doit inclure la réponse payload du corps de la demande. Votre code peut modifier les valeurs des propriétés ou les variables de contexte, mais le message retourné doit respecter le schéma de la méthode message . Pour plus d'informations, consultez la documentation de l'API.

Exemple 1

Cet exemple vous montre comment vérifier la langue du texte d'entrée et ajouter les informations relatives à la langue à la chaîne de texte d'entrée.

Dans la page de configuration du webhook pré-message, les valeurs suivantes sont spécifiées :

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

• Nom de l'en-tête : Type-Contenu

• Valeur d'en-tête : application / json

Le webhook de pré-message appelle une action web IBM Cloud Functions nommée check_language.

Le code node.js de l'action Web check_language se présente comme suit.

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
}
};

Pour tester le webhook, cliquez sur Aperçu. Envoyez le texte Buenos días. L'assistant ne peut probablement pas comprendre l'entrée et renvoie la réponse de votre nœud Anything else. Cependant, si vous allez sur la page Analyse de votre assistant et que vous ouvrez Conversations, vous pouvez voir ce qui a été soumis. Vérifiez la conversation des utilisateur la plus récente. Le journal indique que l'entrée de l'utilisateur est Buenos días (in es). Le es entre parenthèses représente le code de langue pour l'espagnol. Le webhook a donc fonctionné et a reconnu que le texte soumis était une phrase en espagnol.

Exemple 2

Cet exemple vous montre comment vérifier la langue du message entrant et, s'il ne s'agit pas de l'anglais, le traduire en anglais avant de le soumettre à l'assistant.

Définissez une séquence d'actions Web dans IBM Cloud Functions. La première action de la séquence vérifie la langue du texte entrant. La deuxième action de la séquence traduit le texte de sa langue d'origine vers l'anglais.

Dans la page de configuration du webhook pré-message, les valeurs suivantes sont spécifiées :

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

• Nom de l'en-tête : Type-Contenu

• Valeur d'en-tête : application / json

Le code node.js pour la première action Web de votre séquence se présente comme suit :

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
}
};

La seconde action Web de la séquence envoie le texte au service Watson Language Translator pour traduire le texte d'entrée de la langue qui a été identifiée dans l'action Web précédente en anglais. La chaîne traduite est alors envoyée à votre assistant à la place du texte d'origine.

Le code node.js pour la seconde action de votre séquence se présente comme suit :

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
    }
};

Lorsque vous teste le crochet dans le panneau de prévisualisation, vous pouvez soumettre Buenos días et l'assistant répond comme si vous avez indiqué Good morning en anglais. En fait, lorsque vous consultez la page Analyse de votre assistant et que vous ouvrez Conversations, le journal indique que l'entrée de l'utilisateur était Good morning.

Vous pouvez ajouter un webhook post-message pour traduire la réponse du message dans la langue du client avant qu'elle ne soit affichée. Pour plus d'informations, voir l' exemple 2.

Exemple 3

Cet exemple montre comment composer une réponse de webhook afin que watsonx Orchestrate ignore le traitement du message et renvoie directement la réponse du webhook.

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;
}

Retrait du webhook

Si vous ne souhaitez pas prétraiter les données des clients à l'aide d'un webhook, suivez les étapes suivantes :

1. Dans votre assistant, allez dans Environnements et ouvrez l'environnement dans lequel vous souhaitez supprimer le webhook.

2. Cliquez sur l'icône pour ouvrir les paramètres de l'environnement.

3. Sur la page des paramètres de l'environnement, cliquez sur Pre-message webhook.

4. Effectuez l'une des opérations suivantes :

   • Pour ne plus appeler un webhook pour traiter chaque message entrant, réglez le commutateur webhook Pré-message sur Désactivé.

   • Pour modifier le webhook que vous souhaitez appeler, cliquez sur Supprimer le webhook.