Création d’une application Bolt

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

Activer l’accès à Slack pour votre application Bolt
Expliquer ce que sont les fonctions d’écouteur
Ajouter des écouteurs d’événement à votre application
Rendre votre application plus interactive

Remaniement du modèle d’application Bolt for JavaScript dans Glitch

Maintenant que l’application est configurée et installée, il est temps de configurer une nouvelle application Bolt avec les informations d’identification de votre application.

Pour simplifier le développement, ce module utilise Glitch, un outil qui simplifie la création et l’hébergement d’applications. Bien qu’un compte Glitch gratuit soit idéal pour le développement, votre serveur ne fonctionnera pas lorsque que votre application est inactive. Cela signifie que vous devrez garder Glitch ouvert dans votre navigateur pendant que vous développez et testez votre application.

Lorsque votre application sera prête pour la production, il sera peut-être judicieux de l’héberger ailleurs ou de mettre à niveau votre compte Glitch. Une liste complète des fournisseurs d’hébergement recommandés figure sur le site de l’API.

Si vous préférez exécuter votre application localement, vous pouvez utiliser un outil tel que ngrok. Un exemple d’utilisation de ngrok figure dans le Guide de mise en route de la documentation.

Ouvrez votre environnement Glitch.
Cliquez sur ce lien pour remanier (ou cloner) le projet de démarrage Bolt.
Une fois le remaniement terminé, le projet apparaît dans votre liste de projets. Dans l’exemple, il s’appelle actually-triangular-pigeon.
Cliquez sur votre projet pour le charger.
Ensuite, cliquez sur app.js.

Dans le fichier app.js, vous pouvez voir que le package @slack/bolt est importé et instancié. Pour cette raison, le serveur de l’application est configuré et exécuté afin de pouvoir recevoir les événements entrants de Slack.

Vous en ajouterez davantage plus tard. Tout d’abord, renseignez les identifiants issus de la configuration de votre application Slack. N’oubliez pas de garder Glitch ouvert tout au long de ce processus.

Retournez à la page de votre application sur le site de l’API Slack.

Ajout des identifiants de l’application

Récupérez votre secret de signature et votre jeton d’accès OAuth d’utilisateur de robot.

Rendez-vous sur la page de configuration de votre application Slack sur le site de l’API Slack.
Cliquez sur Basic Information (Informations de base) dans la barre latérale.
Faites défiler jusqu’à la section App Credentials (Identifiants de l’application).
Copiez votre secret de signature et enregistrez-le dans votre éditeur de texte pour l’étape suivante.
Cliquez sur OAuth & Permissions (OAuth et autorisations) dans la barre latérale.
Cliquez sur Copy (Copie) pour copier votre jeton d’accès OAuth d’utilisateur de robot et l’enregistrer pour l’étape suivante.

Une fois votre secret et votre jeton sauvegardés, retournez sur Glitch.

Dans votre projet Glitch, accédez au fichier .env situé dans la barre latérale gauche.
Collez votre jeton d’accès OAuth d’utilisateur de robot dans le champ Variable Value (Valeur de la variable) directement après SLACK_BOT_TOKEN (1).
Collez votre secret de signature dans le champ Variable Value (Valeur de la variable) directement après SLACK_SIGNING_SECRET (2). L’application utilise le secret de signature pour vérifier que les requêtes entrantes proviennent bien de Slack. Bolt gère automatiquement la vérification lorsque le secret de signature est transmis au constructeur d’application.

Si vous cliquez sur Logs (Journaux) en bas du navigateur de fichiers de Glitch, vous devriez voir que votre application Bolt est en cours d’exécution.

Journaux ouverts, avec le message Bolt app is running! (L’application Bolt est en cours d’exécution !)

Découverte des fonctions d’écouteur

Les applications Slack reçoivent et répondent généralement à une ou plusieurs requêtes de Slack. Pour chaque type de requêtes entrantes de Slack, il existe une fonction d’écouteur correspondante qui s’occupe de les traiter et d’y répondre.

Voici un sous-ensemble des écouteurs auxquels les applications Bolt peuvent transmettre une fonction.

Écouteur	Description
`app.event(eventType, fn)`	Écoute les événements de l’API d’événements. eventType est une chaîne utilisée pour identifier un événement spécifique.
`app.message([pattern ,], fn)`	Écouteur de commodité servant à traiter les événements de type message. Le modèle peut être n’importe quelle sous-chaîne ou expression régulière.
`app.action(actionId, fn)`	Écoute les événements interactifs d’un élément de bloc, tels qu’une interaction d’un l’utilisateur avec un bouton. L’identifiant actionId est une chaîne qui correspond à l’action_id d’un élément de bloc.
`app.shortcut(callbackId, fn)`	Écoute les invocations de raccourci globales et de message. L’élément callbackId est une chaîne ou un modèle d’expression régulière qui correspond à l’élément callback_id d’un raccourci, qui est spécifié dans la configuration de l’application.

La liste complète est disponible dans la documentation de référence de Bolt. Il est temps de configurer votre application pour écouter les événements, les interactions et les situations d’interactivité et y répondre !

Pour écouter les événements de l’API d’événements, votre application doit activer les abonnements aux événements.

Rendez-vous sur la page de votre application Slack sur le site de l’API Slack, si vous n’y êtes pas déjà.
Cliquez sur Event Subscriptions (Abonnements aux événements) dans la barre latérale.
Les abonnements aux événements devraient s’activer automatiquement. Vous pouvez également les activer manuellement si nécessaire.
Une zone de saisie vous permettant de saisir une URL de requête vous est présentée. Les URL de requête représentent l’emplacement où sont envoyées les requêtes HTTP correspondant aux événements auxquels votre application est abonnée. Si vous avez créé votre application à partir du modèle, votre URL de requête est actuellement https://nom-du-projet.glitch.me/slack/events.
À la place de nom-du-projet, indiquez le nom de votre propre projet Glitch.
1. Cliquez sur Settings (Paramètres), puis sur Go to project page (Accéder à la page du projet). L’URL du site en ligne contient le nom de votre projet : il s’agit du texte figurant après https:// et avant .glitch.me.
Revenez à la page Events Subscriptions (Abonnements aux événements) sur le site de l’API Slack et saisissez l’URL de requête. Elle devrait ressembler à ceci : https://actually-triangular-pigeon.glitch.me/slack/events
Bolt for JavaScript écoute par défaut toutes les requêtes entrantes au niveau du chemin /slack/events, c’est pourquoi ce dernier est ajouté à l’URL de requête.
Cliquez sur Save Changes (Enregistrer les modifications) pour sauvegarder votre travail.
Ensuite, cliquez sur Subscribe to bot events (S’abonner aux événements de robot) pour ouvrir la session. Ici, vous voyez message.channels sous Event Name (Nom de l’événement). Cet événement écoute tous les messages publiés sur les canaux publics dans lesquels est présente votre application. Une fois l’URL de requête activée, votre application devrait commencer à recevoir ces événements.

Ajout d’un écouteur d’événements

Les abonnements aux événements emploient l’écouteur event(), dont vous pouvez trouver des exemples dans la documentation Bolt. Pour l’instant, vous allez utiliser l’écouteur message() afin d’écouter les messages et d’y répondre.

Accédez à votre projet Glitch.
Ajoutez ce qui suit à votre fichier app.js juste sous la partie // Space for your code (// Espace pour votre code).

app.message('hello', async ({ message, say }) => {
    await say(`Hey there <@${message.user}>`);
});

Glitch enregistre automatiquement votre travail.

Le fichier app.js, avec le code saisi juste en dessous de la partie // Space for your code (// Espace pour votre code) mis en évidence par un cadre rouge

En arrière-plan, l’écouteur message() a la même utilité que app.event(“message”, fn), à part le fait qu’il transmet en plus le paramètre say() à la fonction d’écouteur. Le paramètre say() expose l’URL de réponse de l’événement qui, contrairement à lorsqu’on appelle chat.postMessage(), ne nécessite pas de portées supplémentaires pour répondre aux événements message.

Tant que Glitch est opérationnel dans un onglet séparé, votre application devrait redémarrer automatiquement. Vous pouvez désormais envoyer un message contenant « hello » (bonjour) à l’intérieur du canal auquel votre application est ajoutée. L’application devrait normalement répondre.

Canal Slack avec un message Hello (Bonjour) de la part de FS3 et la réponse Hey there @FS3 (Salut @FS3) de la part de sample_app

Cet exemple de base vous donne un point de départ pour personnaliser votre application en fonction de votre cas d’utilisation. Essayons maintenant quelque chose d’un peu plus interactif, en envoyant un élément de bouton plutôt qu’un texte brut.

Configuration de l’interactivité

Pour utiliser des fonctionnalités telles que les boutons, les menus de sélection, les sélecteurs de date, les boîtes de dialogue et les raccourcis, vous devez activer l’interactivité. Comme pour les abonnements aux événements, vous devez spécifier une URL de requête pour que Slack envoie la requête d’action (par exemple, un utilisateur a cliqué sur votre bouton).

Revenez à la page de configuration de votre application Slack et cliquez sur Interactivity & Shortcuts (Interactivité & Raccourcis) dans la barre latérale.
Définissez Interactivity (Interactivité) sur On (Activé). Vous remarquerez la présence d’une autre zone Request URL (URL de requête).
Par défaut, Bolt est configuré de sorte à employer pour les composants interactifs le même point de terminaison qu’il utilise pour les événements. Utilisez donc la même URL de requête que celle mentionnée précédemment.
Cliquez sur Save Changes (Enregistrer les modifications) en bas à droite de la page, et vous avez terminé ! Votre application est maintenant configurée pour gérer l’interactivité.

Ajout d’un écouteur Action pour répondre à un message

Lorsque vous écoutez l’interactivité, vous utilisez l’écouteur action(). Avant de configurer l’écouteur action(), vous devez modifier l’écouteur message() de sorte à ce qu’il envoie un élément de bouton.

Accédez à votre projet Glitch.
Dans app.js, remplacez l’extrait de code précédent afin d’inclure une nouvelle section.

// Message listener function called for messages containing "hello"
app.message('hello', async ({ message, say }) => {
    await say({
        "blocks": [
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": `👋 Hey there <@${message.user}>`
                },
                "accessory": {
                    "type": "button",
                    "text": {
                        "type": "plain_text",
                        "text": "Click Me",
                        "emoji": true
                    },
                    "action_id": "click_me_button"
                }
            }
        ]
    });
});

Remplacement de l’extrait de code précédent par le code ci-dessus, mis en évidence par un cadre rouge

La valeur de say() est désormais un objet contenant un groupe de blocs. Les blocs sont les composants des messages Slack. Il peut s’agir de texte, d’images ou de sélecteurs de date. Ici, l’objet contient un bloc de section qui comprend un bouton en tant qu’accessoire.

Pour concevoir des messages et d’autres surfaces Block Kit, vous pouvez utiliser Block Kit Builder. Cet outil dispose d’un ensemble de modèles intégrés dédiés aux cas d’utilisation courants et d’une interface pratique fonctionnant par glisser-déposer indiquant la charge utile JSON correspondante sur la droite.

Par défaut, Block Kit ne peut pas renseigner les notifications ou effectuer de recherches. Le champ text (texte) doit donc être utilisé pour rendre vos messages plus accessibles. Pour en savoir plus sur le champ text (texte), référez-vous aux informations figurant sur la page de référence relative à chat.postMessage

Dans l’objet d’accessoire bouton figure un paramètre action_id. Il agit comme un identifiant unique que vous pouvez transmettre à votre fonction d’écouteur afin qu’elle n’écoute que les événements interactifs correspondant à cet élément de bloc.

Procédez au redémarrage de votre application. Après cela, vous pouvez envoyer un autre message contenant hello (bonjour), auquel votre application répondra avec un message contenant l’élément de bouton. Toutefois, si vous cliquez sur le bouton, rien ne se passe (pour le moment !).

Dans le canal, FS3 publie le message hello (bonjour), auquel sample_app répond avec un émoji en forme de main qui salue et le texte Hey there @FS3 (Salut @FS3)

Ajout d’un écouteur d’action pour répondre à une interaction avec un bouton

Ajoutons une fonction d’écouteur action() pour répondre au clic sur le bouton avec un message adapté.

Revenez à votre projet Glitch.
Ajoutez l’écouteur d’action suivant dans app.js :

// Action listener function called when an interactive component with action_id of “click_me_button” is triggered
app.action('click_me_button', async ({ ack, body, client, say }) => {
    // Acknowledge action request before anything else
    await ack();
    let channelID = body.channel.id
    let userID = body.user.id
    // Respond to action with an ephemeral message
    await client.chat.postEphemeral({
    channel: channelID,
    user: userID,
    text: `<@${userID}> clicked the button! 🎉 `
  });
});

Vous remarquerez que ack() est appelé à l’intérieur de la fonction d’écouteur. ack() permet de confirmer que votre application a reçu l’événement de Slack. Une fois votre application redémarrée, vous pouvez cliquer à nouveau sur le bouton et votre application répondra avec le nouveau message.

Dans le canal, FS3 publie le message hello (bonjour), auquel sample_app répond avec un émoji en forme de main qui salue et le texte Hey there @FS3 (Salut @FS3), puis, après le clic sur le bouton, sample_app répond @FS3 clicked the button! (@FS3 a cliqué sur le bouton !) avec un émoji représentant des confettis

Si vous rencontrez des problèmes pour exécuter l’application, jetez un œil au code terminé dans actions.js au sein du dossier des exemples de votre projet.

Prochaines étapes

Vous disposez maintenant de votre première application Bolt for JavaScript qui s’appuie sur les concepts de base de Bolt pour écouter les différents événements provenant de Slack et y répondre !

Maintenant que vous maîtrisez les fondamentaux, vous pouvez commencer à vous intéresser à d’autres fonctionnalités de Bolt et de la plate-forme. Voici quelques pistes que vous pouvez envisager d’explorer.

Parcourez le dossier des exemples dans votre projet Glitch. Vous y trouverez quelques fichiers contenant différents exemples de code que vous pouvez copier-coller dans votre projet.
Lisez la documentation de Bolt for JavaScript pour en savoir plus sur les fonctionnalités avancées et trouver des extraits de code présentant ce qu’il est possible d’accomplir.
Améliorez la conception de votre application en utilisant l’outil Block Kit Builder.

Intéressez-vous à d’autres surfaces auxquelles votre application a accès, comme l’onglet d’accueil et les boîtes de dialogue contextuelles.