Skip to main content

Slack

Add your agent to Slack so people can message it in shared channel threads or direct messages. When someone sends a message, Mastra runs your agent through the normal agent pipeline and streams the response back to Slack. The Slack adapter handles Slack AI indicators and interactive cards for you.

Installation
Direct link to Installation

Install the Slack adapter from the Chat SDK:

npm install @chat-adapter/slack

Add createSlackAdapter() to the agent's channels.adapters object:

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(),
    },
  },
})

Create a Slack app
Direct link to Create a Slack app

To connect your agent, create a Slack app in the workspace where you want it to run. The Slack app controls how your agent appears in Slack, what it can do, and which events it receives.

This guide uses a manifest: a configuration file that creates the Slack app settings for you. This is the fastest path when you are adding your agent to your own workspace. It doesn't cover the platform OAuth flow where other workspaces install your agent.

Create the Slack app from a manifest:

  1. Open api.slack.com/apps.
  2. Select Create an app.
  3. Select From a manifest.
  4. Choose the workspace where the agent should run.
  5. Paste this manifest, then select Create:
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

This manifest configures:

  • display_information.name and features.bot_user.display_name: Set your agent's name in Slack. You can update it at any time; remember to reinstall the app after changing names or permissions.
  • app_home.messages_tab_enabled and app_home.messages_tab_read_only_enabled: Enable direct messages from the Slack app's Messages tab.
  • always_online: Shows the Slack bot user as always available.
  • oauth_config.scopes.bot: Grants the bot permission to post messages, read channel messages where it is present, read mentions, read and write direct messages, and look up users.
  • event_subscriptions: Tells Slack which message events to send to the webhook.
  • interactivity: Enables interactive cards and tells Slack where to send card actions.

After the app is created, open Install App, select Install to Workspace, and approve the requested scopes.

Set Slack credentials
Direct link to Set Slack credentials

Set the Slack credentials in Mastra so it can verify Slack requests and send messages back to Slack.

In the Slack app settings, copy these values:

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

Set them in your Mastra environment:

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

Mastra reads these environment variables automatically.

Configure the webhook route
Direct link to Configure the webhook route

Slack sends channel activity to Mastra through webhooks. A webhook is an HTTP endpoint Slack calls when something happens, such as a new message, a mention, or a user selecting an interactive card.

Mastra automatically registers a Slack webhook route for your agent:

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

Build the webhook URL from your public Mastra server URL and the generated route:

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

Slack can't send events to localhost. For local development, keep the Mastra dev server running and expose http://localhost:4111 with a tunnel before you save the request URL in Slack.

Use a tunnel such as cloudflared or ngrok for local development:

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

Use the generated tunnel host as <YOUR-PUBLIC-URL>, for example:

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

Update the request URLs in Slack:

  1. In the Slack app settings, open Event Subscriptions.
  2. Replace Request URL with the final webhook URL.
  3. Select Save Changes.
  4. Open Interactivity & Shortcuts.
  5. Replace Request URL with the same webhook URL.
  6. Select Save Changes.
  7. If Slack asks you to reinstall the app, open OAuth & Permissions and select Reinstall to Workspace.

Try it in Slack
Direct link to Try it in Slack

Open a direct message with the Slack bot user and send a message. Direct messages work because the manifest includes the message.im event and im:* scopes.

To use the agent in a channel, invite the Slack bot user first:

/invite @your-bot-name

Mention the bot in the channel:

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

The agent responds in the thread. Response content depends on the model, instructions, memory, and tools configured on the agent.

Production deployment
Direct link to Production deployment

When you deploy the Mastra server, update both request URLs in the Slack app settings to the production webhook URL. The tunnel URL used for local development is temporary and changes when the tunnel restarts.

Channels on serverless platforms may need waitUntil and shared pub/sub configuration so background responses and thread leases work across short-lived instances. See serverless deployment in the channels overview.

On this page