Procédure

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

1. Dans votre assistant, accédez à Environnements et ouvrez l'environnement dans lequel vous souhaitez configurer le webhook.

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

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

4. Définissez le commutateur Webhook post-message sur Activé.

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

6. 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 parhttps.

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

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

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

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

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

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

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.

{
    "output": {
      "generic": [
        {
          "response_type": "text",
          "text": "This response is directly from the pre-message webhook."
        }
      ]
    }
}

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

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 :

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 d'environnement.

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

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