Faire un appel après traitement d'un message
Un webhook post-message appelle un service ou une application externe chaque fois que l'assistant fournit une réponse. Le service externe peut traiter la sortie de l'assistant avant qu'elle ne soit envoyée au canal.
Vous pouvez ajouter un webhook post-message à votre assistant si vous souhaitez déclencher le webhook avant que chaque réponse à un message ne soit affichée au client.
Vous pouvez utiliser un webhook post-message pour extraire des réponses personnalisées d'un référentiel de contenu externe, par exemple. Par exemple, vous pouvez définir des actions avec des ID personnalisés dans les réponses au lieu du texte. Le webhook post-message peut transmettre ces identifiants à une base de données externe pour récupérer des réponses textuelles stockées.
Vous pouvez utiliser ce webhook en coordination avec le webhook de pré-message. Par exemple, si vous utilisez le webhook pré-message pour supprimer les informations personnellement identifiables des données saisies par le client, vous pouvez utiliser le webhook post-message pour les ajouter. Si vous utilisez le webhook pré-message pour traduire les données du client dans la langue de l'assistant, vous pouvez utiliser le webhook post-message pour traduire la réponse dans la langue du client avant de la renvoyer. Pour plus d'informations, voir Faire un appel avant traitement d'un message.
Pour les environnements où les nœuds finaux privés sont en cours d'utilisation, gardez à l'esprit qu'un webhook en ligne envoie du trafic sur Internet.
Pour une expérience classique, utilisez un webhook de dialogue si vous avez besoin d'effectuer une action ponctuelle au cours d'une conversation. Par exemple, les conditions sont remplies lorsque l'assistant recueille tous les détails requis, tels que le numéro de compte, l'ID utilisateur et le secret de compte. Pour plus d'informations, voir la rubrique Appel par programmation à partir d'un dialogue.
Définition du webhook
Vous pouvez définir une URL de webhook à utiliser pour traiter chaque réponse de message avant qu'elle ne soit envoyée au canal et montrée au client.
L'appel par programmation au service externe doit répondre aux conditions suivantes :
- L'appel doit être une demande HTTP POST.
- L'appel doit être terminé en 30 secondes ou moins.
- Le format de la demande et de la réponse doit être JSON. Par exemple,
Content-Type: application/json
.
Ne définissez et ne testez pas votre webhook dans un environnement de production où l'assistant est déployé et interagit avec les clients.
Procédure
Pour ajouter les détails du webhook, procédez comme suit :
-
Dans votre assistant, accédez à Environnements et ouvrez l'environnement dans lequel vous souhaitez configurer le webhook.
-
Cliquez sur l'icône
pour ouvrir les paramètres d'environnement.
-
Sur la page des paramètres de l'environnement, cliquez sur Post-message webhook.
Pour l'expérience classique, suivez les étapes suivantes :
-
Pour l'assistant que vous souhaitez configurer, cliquez sur l'icône de
, puis sélectionnez Paramètres.
-
Cliquez sur Webhooks > Post-message webhook.
-
-
Définissez le commutateur Webhook post-message sur Activé.
-
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 post-traitement.
-
-
Dans la zone URL, ajoutez l'URL de l'application externe à laquelle vous souhaitez envoyer des appels de demande POST HTTP.
Par exemple, vous stockez peut-être les réponses de votre assistant dans un système de gestion de contenu distinct. Lorsque l'assistant comprend l'entrée, l'action traitée renvoie un ID unique qui correspond à une réponse dans votre CMS. Pour appeler un service qui extrait une réponse de votre système de gestion des configurations pour un ID unique donné, indiquez l'URL de votre instance de service. Par exemple,
https://example.com/get_answer
.Vous devez spécifier une URL qui utilise le protocole SSL, donc indiquez une URL commençant par
https
. -
Pour configurer l'authentification des webhooks post-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.
- Pour l'expérience classique, remplissez le champ Secret. Pour plus d'informations, voir Ajouter un secret pour l'expérience classique uniquement.
-
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.
-
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.
Pour l'expérience classique, le service envoie automatiquement un en-tête d'autorisation avec un JWT. Si vous souhaitez gérer l'autorisation vous-même, ajoutez votre propre en-tête d'autorisation et le service l'utilisera à la place.
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.
Exemple d'en-tête Nom d'en-tête Valeur d'en-tête Content-Type
application/json
-
Après avoir enregistré la valeur d'en-tête, la chaîne est remplacée par des astérisques et ne peut plus être visualisée.
-
Les détails du webhook sont sauvegardés automatiquement.
Ajout d'un secret pour l'expérience classique uniquement
Pour l'expérience classique, ajoutez une clé privée dans le champ Secret à transmettre lors de la demande d'authentification auprès du service externe :
-
Saisissez la clé sous la forme d'une chaîne de texte, par exemple
purple unicorn
. -
Utilisez un maximum de 1 024 caractères.
-
N'utilisez pas de variables contextuelles.
Le service externe est responsable du contrôle et de la vérification du secret. Si aucun jeton n'est requis, indiquez n'importe quelle chaîne de caractères. Ce champ ne peut pas être laissé vide.
Pour afficher le secret au fur et à mesure que vous le saisissez, cliquez sur l' le mot de passe avant de le taper. Après avoir enregistré le secret, des astérisques remplacent
la chaîne et vous ne pouvez plus la consulter.
Pour plus d'informations sur l'utilisation de ce champ, voir Sécurité des webhooks pour l'expérience Classic uniquement.
Configuration de la gestion des erreurs du webhook pour le post-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 post-traitement est utile mais pas indispensable, envisagez cette option.
-
Renvoyer une erreur au client si l'appel au webhook échoue: Si le post-traitement est essentiel après l'envoi d'une réponse par l'assistant, sélectionnez cette option.
Lorsque vous activez l'option Renvoyer une erreur au client en cas d'échec de l'appel au 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, ajustez ce paramètre pour éviter des perturbations dans le traitement de la réponse.
Test du webhook
Testez votre webhook de manière approfondie avant de l'activer pour un assistant utilisé dans un environnement de production.
Le webhook n'est déclenché que lorsque votre assistant traite un message et qu'une réponse est prête à être renvoyée au canal.
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 discussion Web, par exemple, vous savez que votre webhook a un problème si chaque message de test
que vous soumettez 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 test /message
, afin de voir le code d'erreur et le message complet qui est renvoyé.
Code d'erreur et message | Description |
---|---|
422 Webhook a répondu avec un corps JSON non valide | Le corps de réponse HTTP du webhook n'a pas pu être analysé en tant que JSON. |
422 Webhook a répondu avec le code d'état [500] |
Un problème est survenu avec le service externe que vous avez appelé. Le code a échoué ou le serveur externe a refusé la demande. |
500 Exception de processeur : [connections to all backends failing] |
Une erreur s'est produite dans le micro-service webhook. Il n'a pas pu se connecter aux services de back-end. |
Sécurité des webhooks pour l'expérience classique uniquement
Pour l'expérience classique, authentifiez la demande de webhook en vérifiant le jeton Web JSON (JWT) envoyé avec la demande. Le microservice de webhook génère automatiquement un JWT et l'envoie dans l'en-tête Authorization
avec chaque appel de webhook :
-
Pour les nouveaux webhooks ou les webhooks mis à jour par le biais de l'authentification par édition, l'en-tête d'autorisation est ignoré.
-
Pour les webhooks existants dont l'en-tête d'authentification est enregistré, le bouton Modifier l'authentification est désactivé.
-
La mise à jour d'un webhook existant pour utiliser la nouvelle configuration d'authentification modifiera son comportement.
Si vous devez tester la vérification JWT, vous pouvez ajouter du code au service externe. Par exemple, si vous indiquez purple unicorn
dans le champ Secret, vous pouvez utiliser le code suivant :
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
}
Exemple de corps de demande
Il est utile de connaître le format du corps du webhook post-message de la demande afin que votre code externe puisse le traiter.
La charge utile contient le corps de la réponse que votre assistant renvoie pour l'appel API v2 /message
(avec ou sans état). Le nom de l'événement message_processed
indique que le webhook post-message génère la demande.
Pour plus d'informations sur le corps de la demande de message, voir la référence d'API.
L'exemple suivant montre comment le corps d'une requête simple est formaté :
{
"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"
}
}
}
}
}
Sauter le traitement de l'assistant
Les améliorations apportées aux webhooks de pré-message permettent à watsonx Assistant d'ignorer le traitement des messages et de renvoyer directement la réponse du webhook. Cette fonctionnalité est activée en définissant l' x-watson-assistant-webhook-returnheader
dans la réponse HTTP du webhook.
Avant de commencer
Procédez comme suit :
-
Incluez l'
x-watson-assistant-webhook-returnheader
, quelle que soit la valeur de la réponse HTTP de votre webhook. -
Assurez-vous que la réponse du webhook contient un message de réponse valide, formaté conformément aux exigences de watsonx Assistant.
Cette fonctionnalité permet au webhook de contrôler dynamiquement le flux de conversation, ce qui permet des réponses immédiates en cas de besoin.
Corps de la réponse
Dans le corps de la réponse, le output
n'a pas besoin d'être enveloppé dans une propriété payload
puisqu'il est renvoyé directement au client :
{
"output": {
"generic": [
{
"response_type": "text",
"text": "This response is directly from the pre-message webhook."
}
]
}
}
Pour une mise en œuvre pratique de cette fonctionnalité, voir l'exemple 3.
Exemple 1
Cet exemple montre comment ajouter y'all
à la fin de chaque réponse de l'assistant.
Dans la page de configuration du webhook post-message, les valeurs suivantes sont spécifiées :
Pour l'expérience Classic, le champ Secret n'a aucune valeur.
- URL:
https://your-webhook-url/
- Nom de l'en-tête : Type-Contenu
- Valeur d'en-tête : application / json
Le webhook post-message appelle une action web IBM Cloud Functions nommée add_southern_charm
.
Le code node.js de l'action Web add_southern_charm
se présente comme suit :
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
}
}
}
Exemple 2
Cet exemple montre comment traduire une réponse à un message dans la langue du client. Elle ne fonctionne que si vous suivez les étapes de l'exemple 2 pour définir un webhook de pré-message qui traduit le message original en anglais.
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 original, que vous avez stockée dans une variable contextuelle nommée original_input
dans le
code du webhook pré-message. La seconde action de la séquence traduit le texte de la réponse de la boîte de dialogue de l'anglais dans la langue d'origine utilisée par le client.
Dans la page de configuration du webhook pré-message, les valeurs suivantes sont spécifiées :
Pour l'expérience Classic, le champ Secret n'a aucune valeur.
- URL:
https://your-webhook-url/
- 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.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
}
};
La deuxième action Web de la séquence se présente comme suit :
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
}
};
Exemple 3
Cet exemple montre comment composer une réponse de webhook pour permettre à watsonx Assistant de ne pas traiter le message et de renvoyer directement la réponse du webhook.
Configuration de webhook
Dans la page de configuration du webhook de pré-message, spécifiez les valeurs suivantes :
- URL: https://your-webhook-url/webhook_skip
- Nom de l'en-tête : Content-Type
- Valeur d'en-tête : application/json
Le code node.js de l'action Web webhook_skip se présente comme suit.
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 décidez de ne pas traiter les réponses aux messages à l'aide d'un webhook, suivez les étapes suivantes :
-
Dans votre assistant, allez dans Environnements et ouvrez l'environnement dans lequel vous souhaitez supprimer le webhook.
-
Cliquez sur l'icône
pour ouvrir les paramètres d'environnement.
-
Sur la page des paramètres de l'environnement, cliquez sur Post-message webhook.
Pour l'expérience classique, suivez les étapes suivantes :
-
Pour l'assistant que vous souhaitez configurer, cliquez sur l'icône de
, puis sélectionnez Paramètres.
-
Cliquez sur Webhooks > Post-message webhook.
-
-
Effectuez l'une des opérations suivantes :
-
Pour ne plus appeler de webhook pour traiter chaque message entrant, définissez le commutateur Post-message webhook sur Disabled.
-
Pour modifier le webhook que vous souhaitez appeler, cliquez sur Supprimer le webhook.