Définition du webhook

Vous pouvez définir une URL webhook pour un dialogue, puis appeler le webhook à partir d'un ou plusieurs nœuds de dialogue.

L'appel par programmation au service externe doit répondre aux conditions suivantes :

• L'appel doit être une demande HTTP POST.
• Le corps de la demande doit être un objet JSON (Content-Type: application/json).
• La réponse doit être un objet JSON (Accept: application/json).
• L'appel doit être renvoyé en 8 secondes ou moins. S'ils sont lancés plusieurs fois dans un même appel de message via des noeuds de dialogue, tous ces appels doivent être renvoyés en 8 secondes ou moins.

Si votre service externe ne prend en charge que les requêtes GET, ou si vous devez spécifier des paramètres d' URL de manière dynamique au moment de l'exécution, envisagez de créer un service intermédiaire qui accepte une requête POST avec une charge utile JSON contenant toutes les valeurs d'exécution. Le service intermédiaire peut alors faire une demande au service cible, en passant ces valeurs comme paramètres d'URL, puis renvoyer la réponse au dialogue.

Si vous devez appeler un service qui risque de ne pas revenir dans les 8 secondes, vous pouvez gérer l'appel via une application client personnalisée et transmettre les informations à la boîte de dialogue dans une étape distincte. Pour plus d'informations, voir Demande d'actions client.

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

1. Dans la boîte de dialogue dans laquelle vous souhaitez ajouter le webhook, cliquez sur Webhooks.

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

   Par exemple, pour appeler le service Language Translator, indiquez l' URL de votre instance de service.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   Si l'application externe que vous appelez renvoie une réponse, elle doit pouvoir renvoyer une réponse au format JSON. Pour le service Language Translator, par exemple, vous devez spécifier le format dans lequel vous souhaitez que le résultat soit renvoyé. Pour ce faire, transmettez un en-tête au service.

3. Dans la section Headers, ajoutez les en-têtes que vous souhaitez transmettre au service, l'un après l'autre, en cliquant sur Add header.

   Par exemple, cet en-tête indique que la demande est au format JSON.

   Exemple d'en-tête

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

4. Si le service externe exige que vous transmettiez les données d'authentification de base avec la demande, fournissez ces données. Cliquez sur Add authorization, ajoutez vos données d'identification aux zones User name et Password, puis cliquez sur Save.

   Le produit crée une chaîne ASCII codée en base 64 à partir des données d'identification et génère un en-tête qu'il ajoute automatiquement à la page.

   Exemple d'en-tête

   Nom d'en-tête	Valeur d'en-tête
   Autorisation	Base <encoded-credentials>

   Si vous utilisez l'intégration du chat en ligne et que vous activez la sécurité, vous pouvez utiliser le même jeton que celui utilisé pour sécuriser le chat en ligne dans l'en-tête Authorization. Pour plus d'informations, voir Discussion Web : Réutilisation du jeton JWT pour l'authentification par webhook.

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

Ajout d'un appel webhook à un noeud de dialogue

Pour utiliser un webhook à partir d'un noeud de dialogue, vous devez activer les webhooks sur le noeud, puis ajouter des détails pour l'appel.

1. Recherchez le noeud de dialogue dans lequel vous souhaitez ajouter un appel. L'appel au webhook se produit chaque fois que ce nœud est déclenché au cours d'une conversation avec un utilisateur.

   Par exemple, vous souhaiterez peut-être envoyer un appel au webhook à partir du noeud #General_Greetings .

2. Cliquez pour ouvrir le noeud de dialogue, puis cliquez sur Customize.

3. Accédez à la section Webhook. Réglez le commutateur Call out to webhooks / actions sur On.

4. Sélectionnez Call a webhook, puis cliquez sur Apply.

   Si vous ne l'avez pas déjà activé, le commutateur Multiple conditioned responses est automatiquement défini sur On et vous ne pouvez pas le désactiver. Ce paramètre est activé pour prendre en charge l'ajout de différentes réponses en fonction du succès ou de l'échec de l'appel webhook. Si une réponse est déjà spécifiée pour le nœud, elle devient la première réponse conditionnelle.

5. Ajoutez les données que vous souhaitez transmettre à l'application externe en tant que paires clé et valeur dans la section Parameters.

   Les paramètres sont transmis en tant que propriétés du corps de la demande. Vous ne pouvez pas spécifier de paramètres de requête ou d'URL dans un nœud de boîte de dialogue. Ces paramètres ne peuvent être configurés avec des valeurs statiques que dans le cadre de la définition du webhook. Pour plus d'informations, Définition du webhook.

   Par exemple, si vous appelez le service Language Translator, vous devez fournir des valeurs pour les paramètres suivants :

   Exemple de paramètre

   Clé	Valeur	Description
   model_id	en-es	Identifie les langues d'entrée et de sortie. Dans cet exemple, la demande est pour du texte en anglais (en) à traduire en espagnol (es).
   texte	How are you?	Ce paramètre contient la chaîne de texte que le service doit traduire. Vous pouvez coder cette valeur en dur, transmettre une variable de contexte, telle que $saved_text, ou transmettre directement les données de l'utilisateur au service, en spécifiant <? input.text ?> comme valeur.

   Dans les cas d'utilisation plus complexes, vous pouvez collecter des informations lors d'une conversation avec un utilisateur concernant ses projets de voyage, par exemple. Vous pouvez collecter des dates et des informations de destination et les sauvegarder dans des variables contextuelles que vous pouvez transmettre à une application externe en tant que paramètres.

   Exemple de paramètres de voyage

   Clé	Valeur
   depart_date	$departure
   arrive_date	$arrival
   origin	$origin
   destination	$destination

6. Toute réponse apportée par l'appel est enregistrée dans la variable return. Vous pouvez renommer la variable automatiquement ajoutée à la zone Return variable. Si l'appel génère une erreur, cette variable est définie sur null.

   Le nom de la variable générée a la syntaxe webhook_result_n, où le suffixe _n est incrémenté chaque fois que vous ajoutez un appel de webhook à un nœud de dialogue. Cette convention d'appellation garantit que les noms des variables contextuelles sont uniques dans le dialogue. Si vous modifiez le nom, veillez à utiliser un nom unique.

7. Dans la section des réponses conditionnelles, deux conditions de réponse sont ajoutées automatiquement, une réponse indiquant que l'appel Webhook a abouti et qu'une variable de retour est renvoyée. Et une réponse à afficher lorsque l'appel échoue. Vous pouvez éditer ces réponses et ajouter d'autres réponses conditionnelles au noeud.

   • Si le rappel renvoie une réponse et que vous connaissez le format de la réponse JSON, vous pouvez éditer la réponse du noeud de dialogue pour inclure uniquement la section de la réponse que vous souhaitez partager avec les utilisateurs.

     Par exemple, le service Language Translator renvoie un objet comme celui-ci :

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     Utilisez une expression SpEL qui extrait uniquement la valeur de texte traduite.

     Exemple de réponses conditionnelles

     Condition	Réponse
     $webhook_result_1	Vos mots en espagnol : .
     anything_else	L'appel vers l'application externe a échoué. Faites une nouvelle tentative ultérieurement.

     Si vous utilisez le format recommandé pour la réponse et que la réponse de traduction présentée plus haut est renvoyée, la réponse de l'assistant à l'utilisateur sera la suivante : Your words in Spanish: ¿Cómo estás?

   • Si vous souhaitez fournir une réponse spécifique si l'appel renvoie une chaîne vide, ce qui signifie que l'appel est réussi, mais que la valeur renvoyée est une chaîne vide, vous pouvez ajouter une réponse conditionnelle qui comporte une condition dont la syntaxe est la suivante :

     $webhook_result_1.size() == 0
     

8. Lorsque vous avez terminé, cliquez sur le X pour fermer le noeud. Vos modifications sont automatiquement sauvegardées.

Test des webhooks

Lorsque vous ajoutez pour la première fois un appel à un webhook, il peut être utile de voir exactement ce qui est renvoyé dans la réponse de l'application externe, les données et leur format. Ajoutez cette expression comme texte de réponse pour la réponse conditionnelle de l'appel réussi : $webhook_result_n où n est le numéro approprié pour le webhook que vous testez.

Cette réponse renvoie le corps complet de la variable de retour afin que vous puissiez voir ce que l'appel renvoie et décider quoi partager avec l'utilisateur. Vous pouvez ensuite utiliser les méthodes documentées dans les méthodes du langage Expression pour extraire uniquement les informations qui vous intéressent de la réponse.

Vérifiez si certaines entrées utilisateur peuvent générer des erreurs dans l'appel et définissez des méthodes permettant de gérer ces situations. Les erreurs générées par l'application externe sont stockées dans output.webhook_error.<result_variable>. Vous pouvez utiliser une réponse conditionnelle de la sorte pendant que vous testez pour capturer ces erreurs :

Par exemple, vous pouvez ne pas authentifier correctement la demande (401) ou tenter de transmettre un paramètre avec un nom déjà utilisé par l'application externe. Testez le webhook pour découvrir et corriger ces types d’erreurs avant de déployer le webhook.

Suppression d'un webhook

Si vous décidez que vous ne souhaitez pas effectuer d'appel Webhook à partir d'un noeud de dialogue, ouvrez la page Customize du noeud, puis désactivez Webhooks (Off).

La section Parameters et la zone Return variable sont supprimées de l'éditeur de noeud de dialogue. Cependant, toutes les réponses conditionnelles ajoutées pour vous ou que vous avez vous-même ajoutées sont conservées.

La section Multiple conditioned responses est à nouveau modifiable. Vous pouvez choisir de désactiver cette fonction. Dans ce cas, seule la première réponse conditionnelle est enregistrée en tant que réponse textuelle unique du noeud.

Pour modifier le service externe que vous appelez à partir de noeuds de dialogue, modifiez les détails de Webhook définis sur la page Webhooks de l'onglet Options. Si le nouveau service s'attend à ce que différents paramètres lui soient transmis, veillez à mettre à jour tous les noeuds de dialogue qui l'appellent.

Mise à jour de l'output.générique avec un webhook

Vous pouvez utiliser un webhook pour mettre à jour output.generic et fournir des réponses dynamiques. Pour plus d'informations, voir l'article de blogue How to Dynamically Add Response Options to Dialog Nodes.