Aller au contenu principal

Slack

Ajoutez votre Agent à Slack afin que les utilisateurs puissent lui écrire dans des threads de Channels partagés ou par message direct. Lorsqu’une personne envoie un message, Mastra exécute votre Agent selon son pipeline habituel et diffuse la réponse dans Slack. L’adaptateur Slack gère pour vous les indicateurs d’IA Slack et les cartes interactives.

Installation
Lien direct vers Installation

Installez l’adaptateur Slack du Chat SDK :

npm install @chat-adapter/slack

Ajoutez createSlackAdapter() à l’objet channels.adapters de l’Agent :

src/mastra/agents/your-agent.ts
import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})

Créer une application Slack
Lien direct vers Créer une application Slack

Pour connecter votre Agent, créez une application Slack dans le Workspace où vous souhaitez l’exécuter. Cette application contrôle l’affichage de votre Agent dans Slack, ses fonctionnalités et les événements qu’il reçoit.

Ce guide utilise un manifeste, c’est-à-dire un fichier de configuration qui crée les paramètres de l’application Slack à votre place. Il s’agit de la méthode la plus rapide pour ajouter votre Agent à votre propre Workspace. Le guide ne couvre pas le flux OAuth de plateforme permettant à d’autres Workspaces d’installer votre Agent.

Créez l’application Slack à partir d’un manifeste :

  1. Ouvrez api.slack.com/apps.
  2. Sélectionnez Create an app.
  3. Sélectionnez From a manifest.
  4. Choisissez le Workspace dans lequel l’Agent doit s’exécuter.
  5. Collez ce manifeste, puis sélectionnez Create. Slack accepte les formats JSON et YAML ; utilisez l’onglet qui correspond au format affiché dans la fenêtre de création de l’application :
{
  "display_information": {
    "name": "mastra-agent"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "mastra-agent",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "im:write",
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "users:read",
        "im:read",
        "im:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
      "bot_events": ["app_mention", "message.channels", "message.im"]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

Ce manifeste configure :

  • display_information.name et features.bot_user.display_name : définissent le nom de votre Agent dans Slack. Vous pouvez le modifier à tout moment. Pensez à réinstaller l’application après avoir changé le nom ou les autorisations.
  • app_home.messages_tab_enabled et app_home.messages_tab_read_only_enabled : activent les messages directs depuis l’onglet Messages de l’application Slack.
  • always_online : affiche l’utilisateur bot Slack comme étant toujours disponible.
  • oauth_config.scopes.bot : accorde l’autorisation de publier et de lire les messages dans les Channels où le bot est présent. Cette option couvre également les mentions, les messages directs et la recherche d’utilisateurs.
  • event_subscriptions : indique à Slack quels événements de message envoyer au webhook.
  • interactivity : active les cartes interactives et indique à Slack où envoyer les actions effectuées sur ces cartes.

Une fois l’application créée, ouvrez Install App, sélectionnez Install to Workspace, puis approuvez les scopes demandés.

Définir les identifiants Slack
Lien direct vers Définir les identifiants Slack

Définissez les identifiants Slack dans Mastra afin qu’il puisse vérifier les requêtes Slack et renvoyer des messages à Slack.

Dans les paramètres de l’application Slack, copiez les valeurs suivantes :

  • Basic Information > App Credentials > Signing Secret
  • OAuth & Permissions > Bot User OAuth Token

Définissez-les dans votre environnement Mastra :

.env
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token

Mastra lit automatiquement ces variables d’environnement.

Configurer la route du webhook
Lien direct vers Configurer la route du webhook

Slack transmet l’activité des Channels à Mastra par l’intermédiaire de webhooks. Un webhook est un point de terminaison HTTP que Slack appelle lorsqu’un événement se produit, par exemple un nouveau message, une mention ou la sélection d’une carte interactive par un utilisateur.

Mastra enregistre automatiquement une route de webhook Slack pour votre Agent :

/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

Construisez l’URL du webhook à partir de l’URL publique de votre serveur Mastra et de la route générée :

https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook

Slack ne peut pas envoyer d’événements à localhost. Pour le développement local, laissez le serveur de développement Mastra en cours d’exécution et exposez http://localhost:4111 au moyen d’un tunnel avant d’enregistrer l’URL de requête dans Slack.

Pour le développement local, utilisez un tunnel comme cloudflared ou ngrok :

npx cloudflared tunnel --url http://localhost:4111

Utilisez l’hôte généré par le tunnel comme <YOUR-PUBLIC-URL>, par exemple :

https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook

Mettez à jour les URL de requête dans Slack :

  1. Dans les paramètres de l’application Slack, ouvrez Event Subscriptions.
  2. Remplacez Request URL par l’URL finale du webhook.
  3. Sélectionnez Save Changes.
  4. Ouvrez Interactivity & Shortcuts.
  5. Remplacez Request URL par la même URL de webhook.
  6. Sélectionnez Save Changes.
  7. Si Slack vous demande de réinstaller l’application, ouvrez OAuth & Permissions, puis sélectionnez Reinstall to Workspace.

Tester dans Slack
Lien direct vers Tester dans Slack

Ouvrez une conversation directe avec l’utilisateur bot Slack et envoyez-lui un message. Les messages directs fonctionnent parce que le manifeste inclut l’événement message.im et les scopes im:*.

Pour utiliser l’Agent dans un Channel, commencez par inviter l’utilisateur bot Slack :

/invite @your-bot-name

Mentionnez le bot dans le Channel :

@your-bot-name What can you help me with?

L’Agent répond dans le thread. Le contenu de sa réponse dépend du modèle, des instructions, de la mémoire et des Tools configurés dans l’Agent.

Authentication
Lien direct vers Authentication

L’adaptateur Slack ne possède aucune liste d’utilisateurs autorisés intégrée. Une fois l’application installée, toute personne du Workspace peut parler à l’Agent en lui envoyant un message direct ou en le mentionnant dans un Channel dont il est membre. Slack vérifie chaque requête au moyen du secret de signature, et Mastra exécute l’Agent pour chaque message valide reçu par le webhook.

Le principal mécanisme de contrôle d’accès est l’appartenance aux Channels. Le bot reçoit uniquement les événements issus des messages directs et des Channels auxquels il a été invité. L’ensemble des Channels auxquels le bot appartient détermine donc qui peut le joindre. N’ajoutez pas le bot aux Channels dans lesquels il ne doit pas répondre, et retirez-le d’un Channel pour couper l’accès.

Pour un contrôle plus précis, filtrez selon l’identité de l’expéditeur. Chaque requête contient l’identifiant utilisateur Slack de l’expéditeur dans le contexte de requête du Channel. Vous pouvez ainsi autoriser ou refuser certains utilisateurs dans un processeur d’entrée ou un Tool avant que l’Agent n’agisse.

Authentification du serveur
Lien direct vers Authentification du serveur

La route du webhook Slack est exemptée de l’authentification du serveur Mastra. Slack ne peut pas envoyer de bearer token ; Mastra enregistre donc le webhook du Channel comme route publique et vérifie plutôt chaque requête au moyen du secret de signature Slack. Cette règle s’applique même lorsque vous activez un Provider comme MastraAuthSimple : le reste de votre API demeure protégé, mais la route du webhook repose sur le secret de signature plutôt que sur l’authentification de votre serveur. Veillez à définir SLACK_SIGNING_SECRET afin que l’adaptateur puisse refuser les requêtes qui n’ont pas été signées par Slack.

Channels externes
Lien direct vers Channels externes

Les Channels partagés (Slack Connect) permettent aux utilisateurs d’autres Workspaces de rejoindre une conversation. Si un membre du Workspace ajoute le bot à un Channel partagé, toutes les personnes de ce Channel peuvent parler à l’Agent, y compris les membres externes à votre organisation. Toute personne capable de joindre l’Agent peut également accéder aux Tools et aux données auxquels celui-ci a accès.

Considérez l’ajout du bot à un Channel partagé ou externe comme l’octroi d’un accès à l’Agent aux participants concernés. Avant de le faire, vérifiez que les Tools et les données de l’Agent peuvent être exposés sans risque à des membres externes. Lorsque vous devez restreindre les utilisateurs auxquels l’Agent répond, filtrez selon l’identifiant utilisateur de l’expéditeur.

Contexte de requête
Lien direct vers Contexte de requête

Pour chaque message, Mastra place un objet de contexte du Channel dans le contexte de requête, sous la clé channel. Cet objet contient le nom d’affichage et l’identifiant utilisateur Slack de l’expéditeur, l’identité du bot, ainsi que des informations sur l’origine du message. Lisez-le depuis un processeur d’entrée ou un Tool afin d’identifier l’utilisateur ou de créer un embranchement selon le type de conversation :

src/mastra/tools/whoami.ts
import { createTool } from '@mastra/core/tools'
import type { ChannelContext } from '@mastra/core/channels'
import { z } from 'zod'

export const whoami = createTool({
  id: 'whoami',
  description: 'Return the Slack identity of the current user',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined

    return {
      platform: channel?.platform,
      userId: channel?.userId,
      userName: channel?.userName,
      isDM: channel?.isDM,
    }
  },
})

Le contexte du Channel comprend :

  • botMention, botUserId et botUserName : l’identité du bot dans Slack.
  • channelId et threadId : le Channel Slack et le thread dans lesquels le message est arrivé.
  • isDM : indique si le message est un message direct.
  • platform : identifiant de la plateforme, soit slack pour cet adaptateur.
  • userId et userName : identifiant utilisateur Slack et nom d’affichage de l’expéditeur.

Mastra transforme également ce contexte en un court message système. L’Agent apprend ainsi le nom de la plateforme et sa propre identité, ainsi que le caractère direct ou public de la conversation. Consultez la section Contexte du thread de la présentation des Channels pour savoir comment modifier ce comportement.

Déploiement en production
Lien direct vers Déploiement en production

Lorsque vous déployez le serveur Mastra, remplacez les deux URL de requête des paramètres de l’application Slack par l’URL de webhook de production. L’URL du tunnel utilisée pour le développement local est temporaire et change au redémarrage du tunnel.

Sur les plateformes serverless, les Channels peuvent nécessiter waitUntil et une configuration pub/sub partagée afin que les réponses en arrière-plan et les baux des threads fonctionnent entre les instances de courte durée. Consultez la section Déploiement serverless de la présentation des Channels.

Serveurs inactifs
Lien direct vers Serveurs inactifs

Les serveurs de la plateforme se mettent en veille lorsqu’ils ne reçoivent aucun trafic, ce qui ne pose aucun problème pour Slack. L’événement suivant, comme une mention ou un message direct, réveille le serveur en lui transmettant la requête du webhook, puis celui-ci recommence à traiter les requêtes. Comme prévu, la première réponse après une période d’inactivité peut prendre un peu plus de temps pendant le démarrage du serveur. Slack attend un accusé de réception 200 dans un délai de 3 secondes et retente l’événement jusqu’à trois fois en cas d’échec ou d’expiration de la livraison. Un démarrage à froid très lent peut donc nécessiter une nouvelle tentative avant que l’Agent ne réponde. Les messages suivants reçoivent une réponse à la vitesse habituelle tant que le serveur reste actif.

On this page