SlackProvider

SlackProvider est la solution gérée permettant de connecter des Agents à Slack. Enregistrez-le dans Mastra.channels : il provisionne alors les applications Slack via l’API Manifest, exécute le flux d’installation OAuth, renouvelle les tokens de configuration et achemine les événements Slack vers vos Agents. Utilisez-le lorsque vous souhaitez que Mastra prenne en charge la création et l’installation des applications. Pour la solution de plus bas niveau, dans laquelle vous créez vous-même l’application Slack et configurez les scopes et les webhooks, utilisez plutôt createSlackAdapter dans channels.adapters de l’Agent.

Exemple d’utilisation

Enregistrez le Provider dans le constructeur Mastra. Le token d’actualisation est à usage unique et est renouvelé au démarrage. Les tokens d’accès obtenus sont conservés dans Mastra.storage.

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { SlackProvider } from '@mastra/slack'

export const mastra = new Mastra({
  storage,
  channels: {
    slack: new SlackProvider({
      refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
      baseUrl: process.env.MASTRA_BASE_URL,
    }),
  },
})

Lorsque les identifiants ne sont pas disponibles au moment de la construction (par exemple, s’ils sont saisis dans l’interface utilisateur de l’éditeur ou chargés depuis un coffre-fort), construisez le Provider sans les fournir, puis appelez configure() ultérieurement :

src/mastra/index.ts

const slack = new SlackProvider()

await slack.configure({
  refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
})

Paramètres du constructeur

SlackProviderConfig combine des champs propres à Slack, des remplacements pour l’Adapter Slack (toolDisplay, streaming, typingStatus) et un sous-ensemble sélectionné d’options ChannelConfig (notamment handlers, inlineMedia et state) transmis à chaque Agent connecté. Tous les champs sont facultatifs.

refreshToken?:

string

Token d’actualisation Slack App Configuration utilisé pour le renouvellement automatique des tokens. Il est à usage unique ; chaque renouvellement renvoie une nouvelle paire. Il peut également être fourni ultérieurement via configure(). S’il est omis, le Provider démarre sans configuration et ne peut pas créer d’applications tant que configure() n’a pas été appelé ou que les tokens n’ont pas été chargés depuis le stockage. Générez-le dans la section « Your App Configuration Tokens » sur api.slack.com/apps.

token?:

string

Token d’accès Slack App Configuration destiné à la création programmatique d’applications. Facultatif, car le Provider obtient un nouveau token au démarrage à l’aide de refreshToken.

baseUrl?:

string

URL de base publique pour les callbacks de webhook et OAuth. Requise lors de l’appel à connect() pour créer des applications. Elle peut également être définie via setBaseUrl() ou détectée automatiquement à partir de la configuration du serveur Mastra. Pour le développement local, utilisez un tunnel tel que cloudflared.

encryptionKey?:

string

Clé de chiffrement des données sensibles stockées (secret client, secret de signature, token du bot). Utilisez une chaîne aléatoire d’au moins 32 caractères. Elle peut être définie via la variable d’environnement MASTRA_ENCRYPTION_KEY. Si elle est omise, les secrets sont stockés en texte brut (déconseillé en production).

storage?:

ChannelsStorage

Stockage personnalisé des installations. Utilise par défaut le ChannelsStorage de Mastra issu du stockage global. Déclenche une erreur si aucun stockage persistant n’est disponible.

redirectPath?:

string

= "/"

Chemin de redirection après l’achèvement du flux OAuth.

onInstall?:

(installation: SlackInstallation) => Promise<void>

Appelé lorsqu’un Workspace installe l’application avec succès.

streaming?:

StreamingConfig | false

= true

Envoie à Slack les deltas de texte de l’Agent à mesure qu’ils sont générés. Transmettez { updateIntervalMs } pour personnaliser l’intervalle de publication et de modification, ou false pour mettre le texte en mémoire tampon jusqu’à la fin de l’étape. La désactivation du streaming limite toolDisplay aux modes statiques.

textFormat?:

'markdown' | 'plain'

= 'markdown'

Dialecte du texte de réponse final de l’Agent, transmis à l’Adapter Slack. 'markdown' (valeur par défaut) publie les réponses en Markdown afin que Slack affiche nativement le texte en gras, les liens et les tableaux. 'plain' publie du texte brut littéral ; il sert d’échappatoire pour les Agents invités à produire du mrkdwn Slack. S’applique aux réponses mises en mémoire tampon (streaming: false) et au mode de repli du streaming ; le streaming natif utilise toujours Markdown.

toolDisplay?:

ToolDisplay

= 'grouped'

Mode d’affichage des appels de Tools dans Slack : 'cards', 'text', 'timeline', 'grouped', 'hidden' ou une fonction. 'hidden' masque entièrement l’affichage des appels de Tools et de leurs résultats. 'timeline' et 'grouped' nécessitent le streaming. Avec streaming: false, seuls les modes statiques sont disponibles et la valeur par défaut est 'cards'.

typingStatus?:

boolean | TypingStatusFn

= true

Affiche un indicateur de saisie pendant que l’Agent travaille. Définissez false pour le désactiver, ou transmettez une fonction qui renvoie un texte d’état personnalisé pour chaque fragment du flux (renvoyez undefined pour utiliser la valeur par défaut de ce fragment).

waitUntil?:

WaitUntilFn

Renvoie un waitUntil pour la requête de webhook Slack actuelle. Requis dans les environnements d’exécution serverless où Hono ne peut pas relayer l’ExecutionContext de la plateforme (Vercel, AWS Lambda). Sans lui, l’invocation se fige après l’accusé de réception 200 et interrompt l’exécution en cours. Transmettez directement le waitUntil(promise) du SDK de votre plateforme (par exemple, @vercel/functions). Les utilisateurs de Cloudflare Workers et Netlify n’en ont généralement pas besoin.

resolveWaitUntil?:

WaitUntilResolver

Résout waitUntil à partir du Context Hono de la requête lorsque l’environnement d’exécution l’expose par l’intermédiaire de la requête et que la valeur par défaut du core ne le prend pas en charge. Ordre de résolution : waitUntil → resolveWaitUntil → valeur par défaut du core.

handlers?:

ChannelHandlers

Remplace les gestionnaires d’événements intégrés (onDirectMessage, onMention). Transmis à AgentChannels pour chaque Agent connecté via ce Provider.

inlineMedia?:

ChannelConfig['inlineMedia']

Types de médias à envoyer au modèle en ligne.

inlineLinks?:

ChannelConfig['inlineLinks']

Convertit les URL du texte du message en parties de fichier.

threadContext?:

ChannelConfig['threadContext']

Récupère les messages récents du fil depuis Slack lorsque l’Agent rejoint une conversation en cours.

tools?:

ChannelConfig['tools']

Indique si le Channel expose les Tools du Channel (add_reaction, remove_reaction) via AgentChannels.getTools(). Ces Tools ne sont jamais ajoutés automatiquement à l’Agent : transmettez-les explicitement via tools: { ...channels.getTools() } pour les utiliser.

state?:

ChannelConfig['state']

Adapter d’état pour la déduplication des messages, le verrouillage et les abonnements. Utilise par défaut le MastraStateAdapter reposant sur le stockage configuré de l’instance Mastra, afin que les abonnements persistent après les redémarrages.

chatOptions?:

ChannelConfig['chatOptions']

Options supplémentaires transmises directement au SDK Chat.

logger?:

SlackAdapterConfig['logger']

Logger transmis au SlackAdapter sous-jacent. Utilise par défaut le ConsoleLogger de l’Adapter.

Méthodes

Connexions des Agents

connect(agentId, options?)

Crée une nouvelle application Slack pour l’Agent via l’API Manifest et renvoie un résultat OAuth contenant l’URL d’autorisation vers laquelle rediriger l’utilisateur. Nécessite que baseUrl soit défini. Si une installation en attente existe déjà pour l’Agent, renvoie son URL d’autorisation existante au lieu de créer une application en double.

const result = await slack.connect('support-agent', {
  name: 'Support Bot',
})

// Redirect the user to result.authorizationUrl to install the app

Renvoie : Promise<ChannelConnectResult>

interface ChannelConnectResult {
  type: 'oauth'
  installationId: string
  authorizationUrl: string
}

SlackConnectOptions est sérialisable et peut être conservé pour les Agents stockés :

name?:

string

Nom d’affichage du bot Slack. Utilise par défaut le nom de l’Agent, puis son ID.

description?:

string

Description du bot affichée dans Slack. La valeur par défaut est « {name} - Powered by Mastra ».

iconUrl?:

string

URL d’une image carrée (512 x 512 minimum) pour l’icône de l’application. Elle est téléchargée puis chargée automatiquement dans Slack.

manifest?:

(defaults: SlackAppManifest) => SlackAppManifest

Personnalise le manifeste de l’application Slack avant son envoi à l’API Manifest. Reçoit le manifeste par défaut et renvoie le manifeste final. Utilisez cette option pour des scopes personnalisés, des événements supplémentaires ou des paramètres d’interactivité.

redirectUrl?:

string

URL de redirection après la réussite du flux OAuth. Utilise par défaut le redirectPath du Provider ou /.

disconnect(agentId)

Déconnecte un Agent de Slack en supprimant son application et en retirant l’installation du stockage.

await slack.disconnect('support-agent')

Renvoie : Promise<void>

getInstallation(agentId)

Renvoie l’installation Slack d’un Agent, ou null s’il n’en existe aucune.

const installation = await slack.getInstallation('support-agent')

Renvoie : Promise<SlackInstallation | null>

listInstallations()

Répertorie toutes les installations Slack (informations publiques uniquement), qu’elles soient actives ou en attente.

const installations = await slack.listInstallations()

Renvoie : Promise<ChannelInstallationInfo[]>

Configuration

configure(credentials)

Fournit ou efface les identifiants Slack App Configuration pendant l’exécution. Utilisez cette méthode lorsque les identifiants ne sont pas disponibles au moment de la construction. Transmettez null pour effacer les identifiants et supprimer les tokens stockés.

// Provide credentials (persists to storage immediately)
await slack.configure({ refreshToken: 'xoxe-1-...' })

// Clear credentials and stored tokens
await slack.configure(null)

Renvoie : Promise<void>

setBaseUrl(baseUrl)

Définit l’URL de base publique utilisée pour les callbacks de webhook et OAuth. Utilisez cette méthode lorsque l’URL n’est pas connue au moment de la construction et ne peut pas être détectée automatiquement à partir de la configuration du serveur.

slack.setBaseUrl('https://abc123.trycloudflare.com')

initialize()

Recrée un SlackAdapter pour chaque installation active dans le stockage et injecte AgentChannels dans l’Agent correspondant afin qu’il reçoive les événements Slack au démarrage. Ne provisionne pas automatiquement de nouvelles applications. Utilisez connect() pour en créer une. Mastra appelle cette méthode automatiquement ; il est donc rarement nécessaire de l’appeler directement.

await slack.initialize()

Renvoie : Promise<void>

Manifeste par défaut

Lorsque connect() crée une application Slack, le manifeste généré demande un ensemble par défaut de scopes de bot et d’abonnements aux événements. Remplacez-les à l’aide de l’option manifest de connect().

Scopes de bot par défaut	Événements de bot par défaut
chat:write	app_mention
chat:write.public	message.channels
im:write	message.groups
channels:history	message.im
channels:read	message.mpim
groups:history
groups:read
im:history
im:read
mpim:history
mpim:read
app_mentions:read
users:read
reactions:write
files:read
assistant:write

Accéder au Provider

Accédez au Provider enregistré par l’intermédiaire du getter typé channels, à l’aide de la clé d’ID sous laquelle vous l’avez enregistré :

const result = await mastra.channels.slack.connect('support-agent')

Lorsque la clé n’est connue qu’au moment de l’exécution, recherchez-la à partir de l’ID sous forme de chaîne et transmettez le type concret :

const slack = mastra.getChannelProvider<SlackProvider>('slack')
const result = await slack.connect('support-agent')

Exigence de stockage

SlackProvider nécessite un stockage persistant dans Mastra afin de chiffrer et de conserver les installations ainsi que les tokens de configuration renouvelés. Le constructeur déclenche une erreur si aucun stockage persistant n’est disponible et qu’aucun storage personnalisé n’est transmis.

Ressources associées

• ChannelProvider : interface implémentée par SlackProvider
• Channels : concepts, configuration de la plateforme et solution createSlackAdapter
• Référence des Channels : configuration channels du constructeur Agent