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’app, soit en la créant 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 clavardage

La passerelle est aveugle au 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 app de clavardage est un changement aux paramètres de l’espace de travail
• La permission de créer et d’installer des apps dans l’espace de travail Slack
• Rien de joignable publiquement : la connexion est sortante (Socket Mode), donc le serveur n’a besoin d’aucun port entrant, d’aucun tunnel ni d’aucun domaine

Trois façons d’obtenir l’app

Voie	Ce que vous fournissez	Ce que fait Control Center
Guidée	Un jeton de configuration d’app (xoxe-…)	Crée l’app avec les bonnes portées, les bons événements, Socket Mode et la commande slash ; vous remet 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’app terminée	Les vérifie et se connecte

La voie guidée est la seule qui laisse aussi l’app gérable depuis Control Center, ce qui permet de Personnaliser le robot de clavardage. Une app créée avec Créer dans Slack peut être promue en app gérée plus tard en collant un jeton de configuration dans la boîte de dialogue de connexion.

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

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

1. Générez une paire de jetons de configuration d’app sur api.slack.com/apps et copiez le jeton d’actualisation (xoxe-…)
2. Dans Control Center, allez à 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’app, le nom du robot, les descriptions et la commande slash, puis cliquez sur Créer l’app
5. Suivez les deux étapes restantes qu’affiche la boîte de dialogue, chacune sous forme de lien vers Slack :
   • Basic Information → App-Level Tokens : générez un jeton avec la portée connections:write (xapp-…)
   • Install App : installez-la dans l’espace de travail et copiez le Bot User OAuth Token (xoxb-…)
6. Cliquez sur Coller les identifiants et poursuivez à la section Connexion

Le jeton de configuration change à chaque utilisation. Control Center enregistre la nouvelle valeur au fur et à mesure, de sorte que vous n’avez jamais à le coller de nouveau.

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

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

1. Dans Control Center, allez à 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’app, le nom du robot, les descriptions et la commande slash — ces valeurs voyagent avec le lien
4. Cliquez sur Créer dans Slack. Votre navigateur ouvre la page de création d’app de Slack avec la configuration pré-remplie
5. Choisissez l’espace de travail Slack et confirmez. Les portées, les événements, Socket Mode et la commande slash sont déjà corrects
6. De retour dans Control Center, suivez les deux étapes restantes qu’affiche la boîte de dialogue :
   • Basic Information → App-Level Tokens : générez un jeton avec la portée connections:write (xapp-…)
   • Install App : installez-la dans l’espace de travail et copiez le Bot User OAuth Token (xoxb-…)
7. Cliquez sur Coller les identifiants et poursuivez à la section Connexion

Slack n’indique pas quelle app elle a créée, donc Control Center n’apprend pas l’identifiant de l’app et les liens de l’étape 6 mènent à votre liste d’apps plutôt que directement à cette app. Personnaliser le bot exige un jeton de configuration.

Option C : créer l’app vous-même

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

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

Bot token scopes (OAuth & Permissions) :

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

Event subscriptions (événements du robot) :

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels et message.groups sont ce qui fait fonctionner une réponse dans un fil Slack déjà lié. 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é invoquée en dernier).

App Home : activez l’onglet Messages et laissez-le modifiable, pour que les membres puissent envoyer des messages privés au robot.

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

Connexion

1. Allez à 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. Remplissez les champs :

Champ	Valeur	Où cela se trouve dans Slack
Jeton du bot	xoxb-…	OAuth & Permissions → Bot User OAuth Token
Jeton d’application	xapp-…	Basic Information → App-Level Tokens (connections:write)
Jeton d’actualisation de la configuration d’app (facultatif)	xoxe-…	La paire de jetons de configuration d’app sur api.slack.com/apps

Le préfixe de chaque valeur est vérifié des deux côtés avant que quoi que ce soit ne soit envoyé, de sorte qu’une valeur collée dans la mauvaise case est refusée avec la même phrase dans les deux cas.

4. Cliquez sur Connecter

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

Sans le jeton de configuration d’app facultatif, la connexion fonctionne très bien — vous ne pouvez simplement pas modifier le robot depuis Control Center.

Ce que fait la connexion

• Enregistre les identifiants dans le répertoire propre de l’espace de travail, à côté de sa base de données, lisibles par le propriétaire seulement. Ils ne reviennent jamais vers un client
• Ouvre une connexion Socket Mode pour cet espace de travail et commence à recevoir les mentions, les réponses dans les fils Slack, les messages privés et les commandes slash
• Réarme chaque fil Slack qui était lié 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 pas d’app de clavardage : aucun socket, aucune minuterie, aucun trafic

Où vivent les jetons et pourquoi pas dans le trousseau

Les identifiants du robot sont un fichier JSON simple par fournisseur dans <dataDir>/<workspaceId>/chat_credentials/, écrits de façon atomique et réservés au propriétaire. C’est délibéré, pas un oubli : supprimer un espace de travail dissocie ce répertoire, de sorte que ses jetons partent avec lui, et workspace.export ainsi que les sauvegardes copient workspace.db — pas le répertoire —, de sorte qu’un espace de travail que vous remettez à quelqu’un d’autre ne transporte jamais de jetons de robot actifs à l’intérieur. Le corollaire 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, jamais sur la possession d’un jeton. Un compte Slack doit être lié à un utilisateur Control Center qui est membre avec un rôle d’écriture. La connexion, la déconnexion, la configuration guidée, le lien de configuration et la personnalisation du robot sont tous réservés aux administrateurs.

Vérifier

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

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

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

À quoi ressemble une réponse dans Slack

Au-dessus des mots diffusés en continu se trouve une carte regroupé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 devient complète quand le tour se termine, et en erreur quand l’exécution a échoué, a été interrompue ou a atteint sa limite de tours.

La carte commence dès que le robot accepte la mention — Working on it… — de sorte que le fil Slack ne reste pas silencieux pendant que l’espace de travail est encore en cours de construction. Votre première mention dans un canal Slack crée la conversation, qui clone les dépôts dans lesquels travaille l’agent, de sorte que cette ligne de préparation affiche ensuite 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 plutôt que de vous ignorer. Les mentions suivantes dans le même fil Slack s’ouvrent encore avec Working on it…, puis sautent les étapes de clonage parce que 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. View in Control Center sur la carte ouvre la conversation complète dans l’application de bureau — le lien mène à votre propre serveur Control Center, qui remet le navigateur à l’application.

Si rien ne se produit quand vous cliquez, c’est que le serveur qui a envoyé le message n’est pas joignable depuis la machine sur laquelle vous avez cliqué (un serveur qui n’écoute qu’en boucle locale, 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.

Rotation d’un jeton

Collez de nouveau la nouvelle valeur dans la boîte de dialogue de connexion et cliquez sur Connecter. La connexion remplace toute connexion en cours pour cet espace de travail, de sorte que le socket est rétabli avec les nouveaux identifiants.

Les deux jetons obligatoires doivent être présents à chaque connexion. Le jeton de configuration d’app facultatif conserve sa valeur enregistrée lorsque vous laissez la case vide, de sorte que remplacer un jeton de robot ne vous coûte jamais la possibilité de modifier l’app.

Déconnexion

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

Les liaisons d’espaces et d’utilisateurs sont conservées à dessein : reconnecter la même app restaure chaque fil Slack lié. 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 indique « 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, parce que réessayer indéfiniment un jeton révoqué ne vous vaut qu’une limite de débit. Collez de nouveau les jetons dans la boîte de dialogue de connexion.

Une erreur missing_scope signifie que l’app est installée avec moins de portées que la passerelle n’en a besoin. Ajoutez la portée manquante, réinstallez l’app dans Slack, puis reconnectez.

Tout ce qui est transitoire (un socket coupé, un hoquet de Slack) se reconnecte de lui-même avec une temporisation exponentielle plafonnée à 30 secondes, et la rotation de socket routinière de Slack ne fait pas grimper cette temporisation.

Le robot ne répond pas à une mention

• Le robot est-il dans le canal ? Slack ne livre les messages de canal qu’aux apps 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 qui explique comment se lier. Consultez Lier votre compte Slack
• Êtes-vous membre de l’espace de travail avec un rôle d’écriture ? Un viewer ou un guest s’entend dire que son rôle est en lecture seule. La passerelle n’entreprend jamais de travail pour le compte de quelqu’un qu’elle ne peut pas attribuer
• L’espace de travail a-t-il des agents ? Sans agents, 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. À l’extérieur d’un message privé, la passerelle n’agit que sur un message qui mentionne le robot, ou sur une réponse dans un fil Slack qu’elle possède 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 exigent la fonctionnalité Agents & AI Apps d’un forfait payant ; quand Slack la refuse, la passerelle cesse de la demander pour toute la durée de vie de cette connexion et publie plutôt des réponses entières. Rien n’est perdu — la transcription complète se trouve toujours dans Control Center.

Le streaming exige aussi une ancre de fil Slack, de sorte qu’une réponse qui n’a pas de fil Slack où grandir est publiée entière. La carte de tâche arrive quand même 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 d’elle

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 toute la durée de 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 pas de jeton de configuration d’app. C’est le comportement attendu pour une app créée à la main ou au moyen de Créer dans Slack — Slack n’a jamais dit à Control Center de quelle app il s’agit. Générez une paire de jetons sur api.slack.com/apps et reconnectez en remplissant le jeton d’actualisation.

Une longue réponse est tronquée

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

Guides connexes

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

Concepts connexes

• Passerelles de clavardage