Configurer l’intégration Slack

Ce guide vous montre comment connecter Slack à un espace de travail Control Center, soit en laissant Control Center créer l’application, soit en la construisant vous-même.

Pour une première prise en main guidée, consultez Relier Slack à votre espace de travail.

Slack est le seul fournisseur de chat

La passerelle est écrite sans connaissance du fournisseur, par construction — une interface pilotée par descripteur au-dessus d’un adaptateur par fournisseur —, mais Slack est le seul adaptateur qui existe. Il n’existe aucune implémentation de Discord, Telegram, Teams ou Matrix.

Prérequis

• Le rôle owner ou admin dans l’espace de travail Control Center — connecter une application de chat est une modification des paramètres de l’espace de travail
• L’autorisation de créer et d’installer des applications dans l’espace de travail Slack
• Rien d’accessible publiquement : la connexion est sortante (Socket Mode), le serveur n’a donc besoin d’aucun port entrant, de tunnel ni de domaine

Trois façons d’obtenir l’application

Chemin	Vous fournissez	Control Center fait
Guidée	Un jeton de configuration d’application (xoxe-…)	Crée l’application avec les bons scopes, les bons événements, le Socket Mode et la commande slash ; vous confie les deux étapes pour lesquelles Slack n’a pas d’API
Créer dans Slack	Rien	Ouvre Slack avec la même configuration pré-remplie ; vous choisissez un espace de travail et confirmez
À la main	Les jetons de l’application terminée	Les vérifie et la connecte

Le chemin guidé est le seul qui laisse en plus l’application gérable depuis Control Center, ce qui est précisément ce qui permet de Personnaliser le robot de chat. Une application créée avec Créer dans Slack peut être promue plus tard au rang d’application gérée en collant un jeton de configuration dans la boîte de dialogue de connexion.

Il n’existe volontairement aucun bouton « installer l’application Slack de Control Center ». Installer une application Slack distribuée exige un secret client partagé (Slack n’a pas de PKCE) et le Socket Mode répartit les événements d’une application au hasard entre ses connexions : une application partagée livrerait donc les messages de votre espace de travail aux serveurs d’autres personnes. Chaque espace de travail possède par conséquent sa propre application, et ces trois chemins portent sur le peu de travail que cela vous coûte.

Option A : laisser Control Center créer l’application

1. Générez une paire de jetons de configuration d’application sur api.slack.com/apps et copiez le jeton d’actualisation (xoxe-…)
2. Dans Control Center, allez dans Paramètres → Espace de travail → Général et faites défiler jusqu’à la carte Ponts de messagerie
3. Dans le bloc Slack, cliquez sur Créer l’app pour moi
4. Collez le jeton, ajustez le nom de l’application, le nom du bot, les descriptions et la commande slash, puis cliquez sur Créer l’app
5. Suivez les deux étapes restantes que montre la boîte de dialogue, chacune sous forme de lien vers Slack :
   • Basic Information → App-Level Tokens : générez un jeton avec le scope connections:write (xapp-…)
   • Install App : installez dans l’espace de travail et copiez le Bot User OAuth Token (xoxb-…)
6. Cliquez sur Coller les identifiants et poursuivez avec Connexion

Le jeton de configuration est renouvelé à chaque utilisation. Control Center enregistre la valeur renouvelée au fur et à mesure : vous n’avez donc jamais à le recoller.

Option B : la créer dans Slack, pré-remplie

La même application, sans jeton de configuration — Slack vous ouvre son propre écran de création avec tout le manifeste déjà rempli.

1. Dans Control Center, allez dans Paramètres → Espace de travail → Général et faites défiler jusqu’à la carte Ponts de messagerie
2. Dans le bloc Slack, cliquez sur Créer l’app pour moi
3. Ajustez le nom de l’application, le nom du bot, les descriptions et la commande slash — ils voyagent avec le lien
4. Cliquez sur Créer dans Slack. Votre navigateur ouvre la page de création d’application de Slack avec la configuration pré-remplie
5. Choisissez l’espace de travail Slack et confirmez. Les scopes, les événements, le Socket Mode et la commande slash sont déjà corrects
6. De retour dans Control Center, suivez les deux étapes restantes que montre la boîte de dialogue :
   • Basic Information → App-Level Tokens : générez un jeton avec le scope connections:write (xapp-…)
   • Install App : installez dans l’espace de travail et copiez le Bot User OAuth Token (xoxb-…)
7. Cliquez sur Coller les identifiants et poursuivez avec Connexion

Slack n’indique pas quelle application il a créée : Control Center n’apprend donc pas l’identifiant de l’application et les liens de l’étape 6 mènent à votre liste d’applications plutôt que directement à celle-ci. Personnaliser le bot nécessite un jeton de configuration.

Option C : construire l’application vous-même

Créez une application sur api.slack.com/apps, puis configurez-la comme suit.

Socket Mode : activez-le et laissez toutes les URL de requête vides. Slack refuse un manifeste qui demande à la fois le Socket Mode et la livraison par webhook.

Scopes du jeton de bot (OAuth & Permissions) :

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Abonnements aux événements (événements de bot) :

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels et message.groups sont ce qui permet à une réponse dans un fil Slack déjà relié de fonctionner. Sans eux, seule la première mention arrive.

Commande slash : /cc (n’importe quel nom fonctionne — la passerelle utilise la commande avec laquelle elle a été appelée en dernier).

App Home : activez l’onglet Messages et laissez-le modifiable, pour que les membres puissent écrire en message privé au bot.

Jetons : générez un jeton au niveau de l’application avec connections:write, puis installez l’application et copiez le jeton OAuth de l’utilisateur bot.

Connexion

1. Allez dans Paramètres → Espace de travail → Général et faites défiler jusqu’à la carte Ponts de messagerie
2. Dans le bloc Slack, cliquez sur Connecter Slack
3. Renseignez les champs :

Champ	Valeur	Où le trouver dans Slack
Jeton OAuth de l’utilisateur bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Jeton au niveau de l’application	xapp-…	Basic Information → App-Level Tokens (connections:write)
Jeton d’actualisation de configuration d’application (facultatif)	xoxe-…	La paire de jetons de configuration d’application sur api.slack.com/apps

Le préfixe de chaque valeur est vérifié des deux côtés avant tout envoi : une valeur collée dans le mauvais champ est donc refusée avec la même phrase dans un cas comme dans l’autre.

4. Cliquez sur Connecter

Control Center vérifie le jeton de bot avec auth.test de Slack avant d’enregistrer quoi que ce soit : une faute de frappe vous est donc signalée plutôt que de devenir un socket qui ne fonctionne jamais en silence. Le jeton au niveau de l’application ne peut être prouvé qu’en ouvrant le socket, donc un mauvais jeton apparaît un instant plus tard sous forme d’erreur de connexion sur la même ligne.

Sans le jeton de configuration d’application facultatif, la connexion fonctionne parfaitement — vous ne pouvez simplement pas modifier le bot depuis Control Center.

Ce que fait la connexion

• Stocke les identifiants dans le répertoire propre de l’espace de travail, à côté de sa base de données, en lecture réservée au propriétaire. Ils ne repartent jamais vers un client
• Ouvre une connexion Socket Mode pour cet espace de travail et se met à recevoir les mentions, les réponses dans les fils Slack, les messages privés et les commandes slash
• Réarme chaque fil Slack relié auparavant, de sorte qu’une reconnexion poursuit les conversations existantes au lieu de les abandonner
• Ne coûte rien aux espaces de travail qui n’ont aucune application de chat : ni socket, ni minuteurs, ni trafic

Où vivent les jetons et pourquoi pas le trousseau

Les identifiants de bot forment un simple fichier JSON par fournisseur à l’emplacement <dataDir>/<workspaceId>/chat_credentials/, écrit de façon atomique et dont les droits sont réduits au seul propriétaire. C’est délibéré, pas un oubli : supprimer un espace de travail délie ce répertoire, donc ses jetons partent avec lui, et workspace.export comme les sauvegardes copient workspace.db — pas le répertoire —, de sorte qu’un espace de travail que vous confiez à quelqu’un d’autre ne transporte jamais de jetons de bot actifs à l’intérieur. Le corollaire, c’est que restaurer un espace de travail ailleurs implique d’y reconnecter Slack.

L’accès à la passerelle repose sur l’appartenance à l’espace de travail, et jamais sur la possession d’un jeton. Un compte Slack doit être lié à un utilisateur Control Center qui est membre avec un rôle en écriture. Connexion, déconnexion, configuration guidée, lien de configuration et personnalisation du bot sont tous réservés aux administrateurs.

Vérifier

La ligne Slack affiche une étiquette d’état : En ligne, Connexion…, Erreur de connexion (accompagnée de l’erreur propre à Slack), ou Non connecté. Pour vérifier de bout en bout :

1. Dans Slack, invitez le bot dans un canal : /invite @your-bot-name
2. Mentionnez-le avec une demande
3. Une réponse apparaît dans le fil Slack et un espace correspondant apparaît dans Control Center

Chaque membre qui souhaite utiliser la passerelle lie ensuite son propre compte — voir Lier votre compte Slack.

À quoi ressemble une réponse dans Slack

Au-dessus des mots diffusés en continu se trouve une carte groupée, avec une ligne par étape. La préparation est une ligne dont le titre passe de Working on it… à Cloning … puis à Starting the agent…. Le raisonnement ajoute une ligne Thinking… ; quand cette étape se termine, une courte réflexion peut y apparaître. Chaque outil a sa propre ligne (Read lib/main.dart). La réponse arrive sous forme de texte ordinaire sous la carte. La carte passe à l’état terminé quand le tour se termine, et à l’état en erreur quand l’exécution a échoué, a été interrompue ou a atteint sa limite de tours.

La carte démarre à l’instant où le bot accepte la mention — Working on it… —, de sorte que le fil Slack ne reste pas muet pendant que l’espace de travail se construit encore. Votre première mention dans un canal Slack crée la conversation, qui clone les dépôts dans lesquels travaille l’agent : cette ligne de préparation affiche alors Cloning acme/widgets…, puis Setting up Reviewer…, puis Starting the agent…, puis une ligne Thinking… dès que l’agent raisonne réellement. Sur un gros dépôt, cette première préparation prend un certain temps ; la carte est ce qui vous permet de savoir qu’il travaille au lieu de vous ignorer. Les mentions suivantes dans le même fil Slack s’ouvrent encore sur Working on it…, puis sautent les étapes de clonage, car l’espace de travail est déjà là.

Le raisonnement sous forme de mur de texte et la sortie des outils ne quittent jamais Control Center — la réflexion de la ligne Thinking… est une courte ligne, pas une transcription. Le lien View in Control Center de la carte ouvre la conversation complète dans l’application de bureau — le lien pointe vers votre propre serveur Control Center, qui confie le navigateur à l’application.

Si rien ne se passe au clic, c’est que le serveur qui a envoyé le message n’est pas joignable depuis la machine sur laquelle vous avez cliqué (un serveur accessible uniquement en loopback, cliqué depuis un téléphone, par exemple), ou que Control Center n’y tourne pas. Un serveur sans adresse joignable envoie une carte sans bouton plutôt qu’une carte qui ne mène nulle part.

Renouveler un jeton

Recollez la nouvelle valeur dans la boîte de dialogue de connexion et cliquez sur Connecter. Une connexion remplace celle qui tournait pour cet espace de travail, le socket est donc réétabli avec les nouveaux identifiants.

Les deux jetons obligatoires doivent être présents à chaque connexion. Le jeton de configuration d’application facultatif conserve sa valeur enregistrée quand vous laissez le champ vide : renouveler un jeton de bot ne vous coûte donc jamais la possibilité de modifier l’application.

Déconnecter

Cliquez sur Déconnecter sur la ligne Slack (administrateurs uniquement). Le socket se ferme et les identifiants sont oubliés.

Les liens d’espaces et d’utilisateurs survivent délibérément : reconnecter la même application restaure chaque fil Slack relié. Ce sont des lignes propres à l’espace de travail, donc supprimer l’espace de travail les supprime de toute façon.

Dépannage

La ligne affiche « Erreur de connexion »

Lisez l’erreur affichée à côté de l’étiquette. Un identifiant rejeté (invalid_auth, not_authed, token_revoked, account_inactive) est définitif — la passerelle cesse de réessayer et attend de nouveaux jetons, car réessayer indéfiniment un jeton révoqué ne vous vaut qu’une limitation de débit. Recollez les jetons dans la boîte de dialogue de connexion.

Une erreur missing_scope signifie que l’application est installée avec moins de scopes que la passerelle n’en a besoin. Ajoutez le scope manquant, réinstallez l’application dans Slack, puis reconnectez.

Tout ce qui est transitoire (un socket perdu, un hoquet de Slack) se reconnecte tout seul avec un repli exponentiel plafonné à 30 secondes, et la rotation de socket habituelle de Slack n’aggrave pas ce repli.

Le bot ne répond pas à une mention

• Le bot est-il dans le canal ? Slack ne livre les messages de canal qu’aux applications qui en sont membres. Exécutez /invite @your-bot-name
• Êtes-vous lié ? Un membre non lié reçoit une réponse dans ce fil Slack expliquant comment se lier. Voir Lier votre compte Slack
• Êtes-vous membre de l’espace de travail avec un rôle en écriture ? Un viewer ou un guest est informé que son rôle est en lecture seule. La passerelle ne lance jamais de travail pour quelqu’un qu’elle ne peut pas attribuer
• L’espace de travail a-t-il des agents ? Sans agent, le message est enregistré, mais personne ne peut y répondre

Il répond dans un canal mais ignore les messages ordinaires

C’est voulu. En dehors d’un message privé, la passerelle n’agit que sur un message qui mentionne le bot, ou sur une réponse dans un fil Slack qu’elle contrôle déjà. Tout le reste est la conversation d’autres personnes.

Les réponses arrivent en un seul gros message au lieu d’être diffusées en continu

La ligne indique « Le streaming en direct est désactivé pour cette app Slack — les réponses arrivent en un seul message. » Les réponses en streaming de Slack nécessitent la fonctionnalité Agents & AI Apps sur une offre payante ; quand Slack la refuse, la passerelle cesse de la demander pour le reste de la vie de cette connexion et publie des réponses entières à la place. Rien n’est perdu — la transcription complète est toujours dans Control Center.

Le streaming nécessite aussi un point d’ancrage de fil Slack, donc une réponse qui n’a pas de fil Slack où grandir est publiée entière. La carte de tâche arrive dans les deux cas : sur une réponse entière, elle voyage dans le même message, déjà complète.

La réponse n’a pas de carte au-dessus

Les cartes de tâche de Slack font partie de la même nouvelle surface Agents & AI Apps que le streaming, et Slack ne refuse qu’au moment de l’appel. Quand c’est le cas, Control Center conserve la réponse et abandonne la carte pour le reste de la vie de cette connexion — une réponse sans ligne d’état vaut mieux qu’une ligne d’état sans réponse.

« Control Center a besoin d’un jeton de configuration d’app pour modifier le bot »

La ligne Personnaliser le bot est désactivée parce que la connexion n’a aucun jeton de configuration d’application. C’est le comportement attendu pour une application construite à la main ou créée via Créer dans Slack — Slack n’a jamais dit à Control Center de quelle application il s’agit. Générez une paire de jetons sur api.slack.com/apps et reconnectez-vous avec le jeton d’actualisation renseigné.

Une réponse longue est tronquée

Slack limite un message unique à 40 000 caractères, donc la passerelle tronque à 39 000 et ajoute un pointeur vers Control Center — une réponse raccourcie vaut mieux qu’une réponse que Slack rejette d’emblée. Le texte complet est toujours dans la transcription de l’espace.

Guides connexes

• Lier votre compte Slack
• Personnaliser le robot de chat
• Passerelle de chat

Concepts connexes

• Passerelles de chat