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

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

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

   • Poursuivre le traitement de l'entrée utilisateur sans mise à jour du 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.

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

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

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

8. 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 renvoyée soit au format JSON.

   Exemple d'en-tête

   Nom d'en-tête	Valeur d'en-tête
   Content-Type	application/json

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

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

Configuration de la gestion des erreurs du webhook pour le post-traitement

Vous pouvez décider de renvoyer une erreur dans l'étape de post-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 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 du webhook post-message de la demande afin que votre code externe puisse le traiter.

Le payload contient le corps de la réponse que votre assistant renvoie pour la version 2 de l'appel API /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 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"
                }
            }
        }
    }
}

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 :

• 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 post-message, les valeurs suivantes sont spécifiées :

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

Retrait du webhook

Si vous ne souhaitez pas traiter les réponses aux messages à l'aide d'un webhook, procédez comme suit :

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.

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

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

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