Créer un clavardage d'assistance appuyé par Slack en ColdFusion Partie 4 : Préparer Slack avant d'écrire du code

L'un de mes plus gros irritants avec les tutoriels d'intégration, c'est qu'ils semblent tous commencer au milieu. Étape 1 :

cfhttp(...)

Cool. D'où vient le jeton du bot? C'est quel canal? Pourquoi Slack continue-t-il de dire channel_not_found? C'est quoi, un secret de signature? Est-ce que j'ai sauté quinze pages par accident?

Apparemment.

Au moment où la plupart des tutoriels commencent à montrer du code, quelqu'un a déjà cliqué sur dix-sept boutons, copié six secrets, activé trois paramètres obscurs, sacrifié une petite chèvre aux dieux d'OAuth et omis tout ça discrètement de l'article.

Ne faisons pas ça.

Avant d'écrire la moindre ligne de ColdFusion, configurons correctement Slack. Ça rendra tous les articles qui suivent beaucoup plus simples.

Créer une application Slack

Rendez-vous à l'adresse : https://api.slack.com/apps

Créez une nouvelle application. Choisissez « From Scratch ». Donnez-lui un nom. Points bonis si elle porte une référence obscure à Monty Python. Sélectionnez l'espace de travail dans lequel vous voulez l'installer.

Si vous développez en local, créez un espace de travail de développement. Sérieusement. N'expérimentez pas en production. Vous allez absolument tout casser pendant que vous apprenez. C'est beaucoup plus agréable quand ce qui casse vous appartient.

Votre bot, c'est votre application

L'application elle-même n'envoie pas de messages; c'est le bot qui le fait. Voyez votre bot comme un autre membre de votre équipe.

Il a un nom, une icône, il rejoint des canaux, il envoie des messages, il répond dans des fils de discussion... Chaque message envoyé par votre application proviendra de ce bot. Donnez-lui un nom reconnaissable.

Votre vous du futur sera éventuellement en train de fixer cinquante fils Slack en se demandant quels messages viennent de l'application et lesquels viennent de vrais humains.

Veuillez penser à votre vous du futur. Vous lui en avez déjà assez fait subir.

Installer l'application

Créer l'application ne suffit pas. Slack exige que vous l'installiez dans votre espace de travail. Tant que ce n'est pas fait, votre tout nouveau bot est essentiellement sans emploi.

Après l'installation, vous recevrez votre premier secret important : votre jeton OAuth de l'utilisateur du bot. Il ressemblera à quelque chose comme ceci.

xoxb-...

Traitez-le comme un mot de passe extrêmement important, parce que c'est exactement ce que c'est.. Ne le commitez jamais. Ne le codez jamais en dur. Ne l'envoyez jamais par courriel. Ne le mettez jamais dans une capture d'écran.

Si le jeton de votre bot fuit, quelqu'un d'autre a maintenant la permission de parler au nom de votre application.

Ça peut devenir gênant très rapidement.

Donnez au bot la permission de faire son travail

Slack suit le principe du moindre privilège. Votre bot ne peut pas tout faire par magie. Il a besoin d'autorisations.

Pour ce projet, vous aurez besoin d'un ensemble étonnamment petit de portées OAuth. Au minimum :

• chat:write
• channels:history

Selon votre environnement, vous pourriez aussi avoir besoin de :

• groups:history
• im:history
• mpim:history

N'activez pas aveuglément toutes les autorisations parce que Stack Overflow vous l'a dit. Chaque autorisation augmente les dégâts qu'un jeton compromis peut causer.

Demandez exactement ce dont vous avez besoin. Pas plus.

Décidez de votre stratégie de canaux

C'est une décision étonnamment importante. Vous avez des options :

• Un canal par client.
• Un canal par département.
• Des canaux privés.
• Des messages directs.
• Un seul canal de soutien.

Après avoir essayé plusieurs idées, j'ai retenu la plus simple : un seul canal de soutien et un seul fil Slack par conversation client.

Canal de soutien

Client A
└── Fil

Client B
└── Fil

Client C
└── Fil

C'est remarquablement évolutif. Le personnel de soutien n'a qu'un seul endroit à surveiller. Les conversations restent organisées. La recherche est facile. Le modèle de fils de discussion de Slack fait la majeure partie du travail lourd gratuitement.

Ne sous-estimez jamais la valeur de laisser le logiciel de quelqu'un d'autre résoudre votre problème.

Invitez le bot dans votre canal

Cela piège presque tout le monde.

Votre bot peut avoir la permission d'écrire des messages. Ça ne veut pas dire qu'il est réellement membre du canal auquel vous voulez qu'il envoie des messages. Si Slack renvoie :

not_in_channel

L'API n'est pas brisée. Votre bot n'est tout simplement pas là. Dans Slack, vous devez faire :

/invite @YourBot

Problème réglé. J'ai passé beaucoup plus de temps à découvrir ça que je ne suis à l'aise de l'admettre. J'espère que ce ne sera pas votre cas.

Comprenez ts avant que ça vous embrouille

Slack a une convention de nommage malheureuse. Chaque message a un horodatage. On l'appelle ts. Le premier message d'un fil a son propre ts. Cette valeur exacte devient aussi l'identifiant du fil.

Les réponses n'inventent pas un nouvel identifiant de fil. Elles référencent simplement le message original.

Message original
ts = 1751637712.948372
Réponses
thread_ts = 1751637712.948372

Cette petite valeur devient le pont entre Slack et votre base de données. Stockez-la immédiatement. N'essayez pas de la reconstruire plus tard.

Les bases de données sont bien meilleures pour se souvenir des choses que les développeurs. Surtout les développeurs après le dîner.

Activez l'API Events

À un moment donné, Slack doit répondre à votre application... c'est là qu'entre en jeu l'API Events. Activez-la. Slack demande une URL de requête.

Au début, ça semble à l'envers. Vous n'avez pas encore écrit le point de terminaison, et c'est correct. Nous le construirons dans les deux prochains articles. Comprenez simplement que Slack communique en envoyant des requêtes HTTP ordinaires à votre application.

Rien de magique. Rien de propriétaire.

Juste des webhooks.

Slack vérifiera votre point de terminaison

La première requête envoyée par Slack n'est pas un message; c'est un défi. Slack demande essentiellement : « Avant que je commence à vous envoyer des événements... êtes-vous vraiment là? »

Votre point de terminaison renvoie simplement la valeur du défi. Une fois que c'est fait, Slack est satisfait et, après ça, les vrais événements commencent.

Nous l'implémenterons plus tard en ColdFusion. Pour l'instant, il suffit de savoir pourquoi Slack commence soudainement à parler à un point de terminaison qui n'existe pas encore.

Rassemblez tout ce dont vous aurez besoin

Avant d'écrire du code, rassemblez ces valeurs.

• Jeton OAuth de l'utilisateur du bot
• Secret de signature
• ID du canal
• ID de l'espace de travail
• ID de l'utilisateur du bot
• ID de l'application

Rangez-les quelque part de sécurisé. Variables d'environnement, gestionnaire de secrets, configuration chiffrée... Littéralement n'importe où sauf dans votre code source.

Rien ne gâche autant un vendredi que de découvrir que le jeton de production de votre bot vit dans GitHub depuis six mois.

Testez Slack avant de tester ColdFusion

C'est probablement le conseil le plus important de tout l'article. Ne commencez pas avec ColdFusion. Commencez avec Postman, ou Bruno, ou curl. Pouvez-vous appeler chat.postMessage avec succès? Le bot peut-il publier dans votre canal de soutien? Peut-il répondre à un fil existant?

Si la réponse est non... Arrêtez. N'écrivez pas encore de code d'application. Faites d'abord fonctionner Slack. Quand votre première ligne de ColdFusion échoue, vous devriez déboguer un seul système, pas deux.

N'ayez pas peur de l'API Slack

La documentation de Slack peut sembler intimidante.

Il y a des centaines de points de terminaison. Des milliers d'événements. Assez d'autorisations pour faire sourire un auditeur de sécurité gouvernemental. Ignorez presque tout ça.

Pour ce projet, vous n'utiliserez qu'une infime partie de ce que Slack offre :

• Un point de terminaison pour publier des messages.
• Un point de terminaison pour recevoir des événements.
• Quelques autorisations.
• Un bot.
• Un canal.

C'est vraiment tout. C'est étonnamment petit une fois qu'on cesse de regarder la plateforme entière.

La prochaine fois

Maintenant que Slack est prêt, nous pouvons enfin écrire du ColdFusion.

Nous enverrons notre premier message en utilisant chat.postMessage, créerons automatiquement des fils Slack, stockerons les identifiants de fil dans notre modèle de conversation et construirons la partie sortante de notre pont de soutien.

Parce qu'écrire enfin du code est beaucoup plus satisfaisant une fois qu'on a cessé de se battre avec les écrans de configuration.