Zenbot – Un chatbot qui répond aux questions en consultant la FAQ Zenika

La FAQ Zenika (foire aux questions) est une base de connaissance interne regroupant toutes les informations utiles aux membres de Zenika. Afin de faciliter l’accessibilité à cette base, nous avons souhaité l’intégrer aux messageries couramment utilisées au sein de Zenika via un chatbot.
Zenbot est un chatbot qui permet de répondre aux questions des Z en consultant la FAQ. Dans cet article, je présente en 3 étapes la démarche qui a permis d’intégrer Zenbot aux plateformes Workplace et Slack.

Étape 1 : La configuration d’une application

La première étape de l’intégration d’un bot passe par la configuration d’une application qui représentera le bot et contrôlera ses actions sur la plateforme concernée. Cette configuration se fait manuellement au niveau de chaque plateforme. Elle permet de définir un ensemble d’informations sur le bot telles que son nom, une description, les différentes permissions qui lui sont accordées, etc.

Workplace

Sur Workplace, le réseau social d’entreprise créé par Facebook, il s’agit de créer une Custom Integration. Lorsqu’on crée une Custom Integration, 2 objets sont en fait créés :
– Une application (avec des autorisations qui lui sont spécifiques).
– Une page de type Bot (uniquement visible au sein de votre communauté Workplace). Cette page servira entre autres de point d’entrée et de découverte de votre bot sur workplace.
Pendant la configuration, il vous sera demandé plusieurs informations sur votre bot dont l’URL sur laquelle le contacter. Nous verrons comment obtenir cette URL à l’étape 3.
Il vous sera aussi demandé de définir un token de vérification verify token. Ce token permet de vérifier l’authenticité des échanges entre la plateforme Messenger et le webhook déployé sur votre serveur.
À l’issue de cette configuration, un token (Page Access Token) est généré. Ce token servira par la suite à légitimer toutes les actions de votre webhook en tant que bot associé à l’application que vous venez de créer. Conservez-le précieusement et ne le divulguez qu’aux personnes de confiance (ex : l’équipe de développement). Nous verrons dans la suite de ce readme, comment utiliser ce token.

Vous trouverez plus de détails sur la création d’une application Workplace ici : Creating Apps for Workplace.

Slack

Pour ce qui est de l’intégration de Zenbot dans Slack, j’ai fait le choix d’utiliser les Slash Commands. Les Slash Commands permettent à l’utilisateur d’effectuer des actions (dans notre cas des recherches) en tapant des commandes depuis slack. Par exemple, pour consulter la FAQ à propos des “notes de frais” l’utilisateur pourra taper la commande “/faq note de frais” depuis slack ; il verra alors s’afficher une liste de résultats correspondant à sa recherche.
La page Mes Applications liste l’ensemble des applications que vous possédez sur Slack. Pour en créer une nouvelle, il suffit de cliquer sur le bouton Create New App depuis cette page, puis renseigner le nom de l’application et l’espace de travail (Development Slack Workspace) auquel elle sera associée.
Une fois l’application créée, il va falloir la configurer. Pour ce faire, il faut se rendre sur la page de configuration de l’application en cliquant sur son nom dans la liste des applications. La page de configuration contient nombre d’informations sur l’application dont son identifiant (App Id), le token de vérification (Verification Token), etc. Cette page permet également de gérer les permissions ainsi que les différentes features (Bot, Slash Commands, etc.) dont vous aurez besoin pour faire fonctionner votre application.
Pour intégrer Zenbot à la messagerie Slack, j’ai eu besoin d’activer 2 features :
– Incoming Webhooks : permet de poster des messages dans Slack depuis une source externe.
– Slash Commands : permet aux utilisateurs d’effectuer des actions en tapant des commandes. Cette feature nécessite d’être configurée en renseignant :

•  un nom de commande (ex : /faq)
•  une URL de requête (l’URL que Slack contactera à chaque fois qu’un utilisateur entrera la commande /faq). Nous verrons à l’étape 3 comment obtenir cette URL.
•  une courte description de la commande
•  une instruction d’utilisation (court message expliquant comment utiliser la commande)

Une fois la configuration de l’application et de ses commandes terminées, il faudra installer l’application depuis le volet “Install your app to your workspace”. Vous pourrez également choisir de distribuer votre application sur Slack, au-delà de votre espace de travail.
Pour de plus amples précisions sur la création d’une application, vous pouvez consulter cette page : Building Slack apps.
Et voilà ! Vous savez désormais configurer une application Slack ou Workplace. Nous allons maintenant voir comment coder un webhook pour répondre aux requêtes des utilisateurs.
 

Étape 2 : La création de Webhooks

Un webhook est une fonction de rappel HTTP (user-defined HTTP callback) généralement déclenchée lors d’un évènement (dans notre cas l’envoi d’un message à notre bot).
Pour faire simple, notre webhook jouera le rôle d’intermédiaire entre notre chatbot et l’API de la FAQ Zenika. Il nous permettra de recevoir, gérer et envoyer des messages. À chaque fois qu’un utilisateur écrira un message à notre bot, il sera envoyé au webhook qui effectuera une recherche auprès de l’API de la FAQ, puis retournera une réponse à l’utilisateur.
La création de notre webhook consiste à ajouter quelques points de terminaison (endpoints) à un serveur HTTP comme Express par exemple.

Workplace

La configuration du webhook sur Workplace se fait en 2 étapes :
– L’ajout du endpoint de vérification du webhook : sur ce endpoint seront envoyées des requêtes de type GET servant à contrôler le token de vérification Facebook (Verify Token) défini lors de la configuration de la Custom Integration vue à l’étape 1. Cette étape est requise par la plateforme Messenger pour garantir l’authenticité de notre webhook.

// Adds support for GET requests to our webhook
  app.get('/webhook', (req, res) => {
  // Your verify token. Should be a random string.
  let VERIFY_TOKEN = "<YOUR_VERIFY_TOKEN>"
  // Parse the query params
  let mode = req.query['hub.mode'];
  let token = req.query['hub.verify_token'];
  let challenge = req.query['hub.challenge'];
  // Checks if a token and mode is in the query string of the request
  if (mode && token) {
    // Checks the mode and token sent is correct
    if (mode === 'subscribe' && token === VERIFY_TOKEN) {
      // Responds with the challenge token from the request
      res.status(200).send(challenge);
    } else {
      // Responds with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
  });

– L’ajout du endpoint principal : sur ce endpoint seront envoyées des requêtes de type POST correspondant aux messages envoyés par les utilisateurs.

// Creates the endpoint for our webhook
  app.post('/webhook', (req, res) => {
  let body = req.body;
  // Checks this is an event from a page subscription
  if (body.object === 'page') {
    // Iterates over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {
      // Gets the message. entry.messaging is an array, but
      // will only ever contain one message, so we get index 0
      let webhook_event = entry.messaging[0];
      // Get the sender PSID
      let sender_psid = webhook_event.sender.id;
      // Check if the event is a message or postback and
      // pass the event to the appropriate handler function
      if (webhook_event.message) {
        handleMessage(sender_psid, webhook_event.message);
      } else if (webhook_event.postback) {
        handlePostback(sender_psid, webhook_event.postback);
      }
    });
    // Returns a '200 OK' response to all requests
    res.status(200).send('EVENT_RECEIVED');
  } else {
  // Returns a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
  });

Vous trouverez plus de détails sur la configuration du webhook ici : Webhook Setup.
Messenger définit 2 types d’évènements entrants : les messages et les postbacks. Les messages représentent les messages textuels écrits par l’utilisateur (textos) tandis que les postbacks sont des actions (clic sur un bouton par exemple). Une fois notre endpoint principal configuré, nous aurons besoin de lui ajouter des fonctions de gestion d’évènements :
– une fonction handleMessage pour gérer les textos
– une fonction handlePostback pour gérer les actions (clic boutons, sélections, etc)
– une fonction callSendAPI permettant d’envoyer des messages à l’utilisateur via l’API Send de Messenger

// Handles messages events
function handleMessage(sender_psid, received_message) {
   let response = {};
  //...
  callSendAPI(sender_psid, response);
}
// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {
  let response = {};
  //...
  callSendAPI(sender_psid, response);
}
// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
// Construct the message body
let request_body = {
  "recipient": {
    "id": sender_psid
  },
  "message": response
}
// Send the HTTP request to the Messenger Platform
request({
  "uri": "https://graph.facebook.com/v2.6/me/messages",
  "qs": { "access_token": PAGE_ACCESS_TOKEN }, //do not forget to specify the Page Access Token
  "method": "POST",
  "json": request_body
}, (err, res, body) => {
  if (!err) {
    console.log('message sent!')
  } else {
    console.error("Unable to send message:" + err);
  }
});
}

Il y a ici 2 choses importantes à retenir :
– On appelle toujours la fonction callSendAPI pour envoyer une réponse lors de la réception d’un texto ou d’une action.
– Pour que la requête de réponse soit acceptée par la plateforme Messenger, il faut obligatoirement ajouter dans le paramètre qs (query string), le Page Access Token généré à l’issue de l’étape 1.
Pour finir, il ne nous reste plus qu’à définir la structure de nos réponses. Celles-ci sont généralement au format JSON. Messenger dispose d’une grande variété de templates prédéfinis pour nous aider à construire nos messages de réponse. On peut ainsi, envoyer un simple texto :

response = { "text": `Hello! Je suis Zenbot.` }

ou bien un message riche composé d’un titre, d’une image et de boutons :

response = {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "generic",
          "elements": [{
            "title": "Is this the right picture?",
            "subtitle": "Tap a button to answer.",
            "image_url": attachment_url,
            "buttons": [
              {
                "type": "postback",
                "title": "Yes!",
                "payload": "yes",
              },
              {
                "type": "postback",
                "title": "No!",
                "payload": "no",
              }
            ],
          }]
        }
      }
    }

Vous connaissez maintenant les grandes lignes de la création d’un webhook pour la plateforme Messenger. Vous trouverez ici (quick-start), un tutoriel complet sur la conception d’un bot Messenger.

Slack

Pour rappel, j’ai fait le choix d’utiliser les slash-commands pour intégrer Zenbot à Slack. Les slash-commands sont envoyées de la même manière qu’un message classique depuis la barre d’envoi des messages. Cependant les slash-commands ne sont pas à proprement parler des messages dans la manière dont slack les interprète. La soumission d’une slash-command entraînera l’envoi à notre webhook d’une requête POST contenant en son corps une charge utile de données (payload).
Sur Slack, la création du webhook fonctionne à peu près de la même manière que sur Messenger. Il s’agit toujours de créer un ou plusieurs endpoints sur un serveur HTTP. Ces endpoints recevront les charges utiles envoyées lors des soumissions de la commande /faq puis retourneront une réponse au format JSON.
> À noter que sur slack, la vérification du webhook est possible mais pas obligatoire.
Pour tout savoir du fonctionnement d’une slash-command et de l’implémentation de son webhook associé, ça se passe ici : Slash Commands.
Tout comme Messenger, Slack dispose d’un système de templating pour les réponses au format JSON. Ce système de templating va nous aider à structurer et enrichir nos messages. En plus de la structuration des messages, slack offre une grande variété d’outils de formatage des messages incluant le formatage des dates, l’ajout de fragments de code, etc. La page An introduction to messages explique en détail comment composer un message structuré. Il est également possible de trouver sur le compte Github de Slack un memento des templates les plus couramment utilisés.
Vous trouverez plus de détails sur les intégrations Slack en général ici : Building internal integrations for your workspace.
Nous avons fini de configurer notre webhook, il faut maintenant le déployer pour le rendre disponible sur web.
 

Étape 3 : Le déploiement

Pour déployer notre webhook, j’ai choisi d’utiliser la solution d’hébergement Clever Cloud. Clever Cloud fournit aux développeurs une plateforme de déploiement avec une infrastructure robuste et une mise à l’échelle automatique. L’avantage d’utiliser Clever Cloud réside dans l’automatisation du déploiement de chaque nouvelle version de notre bot. Dans cette étape, nous expliquerons comment déployer notre webhook sur Clever Cloud.
Depuis le tableau de bord de Clever Cloud,  il est possible de créer une nouvelle application. Pour ce faire, il faut :
– cliquer sur le bouton : “create”
– puis choisir “an application”
– et enfin, sélectionner le repository du projet à partir du menu déroulant “Select your Github repository”
– Définir le type d’application que représente le projet en choisissant Node parmi la liste proposée
– Choisir le nombre d’instances nécessaires
– On peut ensuite ajouter une description et une région pour l’hébergement, puis cliquer sur “CREATE” pour lancer la création de notre application sur Clever Cloud
– Nous n’avons pas besoin d’add-on, nous pouvons donc passer l’étape correspondante et cliquer directement sur next
– Il nous est demandé de définir un certain nombre de variables d’environnement. C’est le parfait endroit pour renseigner toutes les valeurs en dur de notre bot, par exemple, le token de vérification qui doit rester confidentiel.
Il faut finalement cliquer sur Next pour lancer le déploiement de notre application sur le web.
La vidéo NodeJS Mongo demo résume bien ces différentes étapes de création d’une application sur Clever Cloud:

Yay ! Notre bot est en ligne 🎉🎉🎉 . Mais attention ce n’est pas fini. Nous devons encore récupérer l’URL sur laquelle notre bot a été déployé et la renseigner dans la configuration de la plateforme d’intégration de notre bot (Messenger/Slack) comme vu à l’étape 1. L’URL de déploiement est disponible et configurable à partir du menu “Domain names” de notre application sur le tableau de bord Clever Cloud.
Et, petite cerise sur le gâteau, il est possible de configurer un message de bienvenue sur Messenger en suivant les instructions de la page Welcome screen.
C’est terminé !
Nous pouvons maintenant tester que tout fonctionne correctement en écrivant quelques messages à notre bot depuis Messenger ou bien en utilisant la commandes /faq sur Slack !
Pour finir, voici les liens vers les documentations respectives des plateformes Messenger et Slack.