# Building a Slack assistant

In this guide, you'll build a Mastra agent that responds to messages and mentions on Slack. You'll learn how to configure a channel adapter, set up a Slack app with the right permissions, connect it to your agent via a webhook, and test the interaction.

## Prerequisites

- Node.js `v22.13.0` or later installed
- An API key from a supported [Model Provider](https://mastra.ai/models)
- An existing Mastra project. Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) if needed.
- A [Slack workspace](https://slack.com/) where you can create apps

## Create the agent

Install the Slack adapter:

**npm**:

```bash
npm install @chat-adapter/slack
```

**pnpm**:

```bash
pnpm add @chat-adapter/slack
```

**Yarn**:

```bash
yarn add @chat-adapter/slack
```

**Bun**:

```bash
bun add @chat-adapter/slack
```

Create a new file `src/mastra/agents/slack-agent.ts` and define your agent:

```ts
import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const slackAgent = new Agent({
  id: 'slack-agent',
  name: 'Slack Agent',
  instructions:
    'You are a helpful assistant. Answer questions, help with tasks, and have natural conversations.',
  model: 'anthropic/claude-opus-4-6',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})
```

The `channels` property tells Mastra to generate a webhook endpoint for each adapter. In this case, the Slack adapter handles event verification, signature validation, and message formatting automatically.

Register the agent in your `src/mastra/index.ts` file:

```ts
import { Mastra } from '@mastra/core'
import { slackAgent } from './agents/slack-agent'

export const mastra = new Mastra({
  agents: { slackAgent },
})
```

## Create a Slack app

You need a Slack app to connect your agent to a workspace.

Go to <https://api.slack.com/apps> and select **Create New App** > **From scratch**. Give it a name and select your workspace.

Navigate to **OAuth & Permissions** and scroll to **Bot Token Scopes**. Add the following scopes:

- `app_mentions:read`
- `channels:history`
- `channels:read`
- `chat:write`
- `users:read`

At the top of **OAuth & Permissions**, select **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).

Go to **Basic Information** > **App Credentials** and copy the **Signing Secret** (e.g. `c3a4...`).

Ensure **Socket Mode** is turned **off** under **Settings** > **Socket Mode**.

Add the credentials to your `.env` file:

```bash
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token
```

The adapter reads these environment variables by default. See the [Chat SDK Slack adapter docs](https://chat-sdk.dev/adapters/slack) for more details.

## Connect the webhook

Slack delivers events to your agent via a webhook. Mastra generates this endpoint automatically for each channel adapter.

Start the dev server:

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

During local development, Slack needs a public URL to reach your local server. Open a new terminal and start a tunnel:

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

This outputs a temporary public URL like `https://triple-arms-solutions-kit.trycloudflare.com`. The URL changes each time you restart the tunnel.

In your Slack app settings, go to **Event Subscriptions** and toggle **Enable Events** to **On**.

Set the **Request URL** to your tunnel URL with the agent webhook path:

```text
https://<your-tunnel-url>/api/agents/slack-agent/channels/slack/webhook
```

Slack sends a verification request. If your dev server is running, it responds with a green checkmark.

Under **Subscribe to bot events**, add:

- `app_mention`
- `message.channels`

Select **Save Changes**. Slack requires you to reinstall the app after changing event subscriptions. Go to **OAuth & Permissions** and select **Reinstall to Workspace** to apply the updated permissions.

> **Note:** The tunnel URL is for local development only. When you [deploy your application](https://mastra.ai/docs/deployment/overview), update the **Request URL** in your Slack app's **Event Subscriptions** to your production URL (e.g. `https://your-app.example.com/api/agents/slack-agent/channels/slack/webhook`).

## Test the agent

Before testing with Slack, you can refine your agent's behavior in [Studio](https://mastra.ai/docs/studio/overview). Open <http://localhost:4111/> to chat with your agent directly, adjust its instructions, and inspect traces to see how responses are generated.

Once you're happy with the agent's responses, test the Slack integration. Invite the bot to a channel in Slack:

```text
/invite @your-bot-name
```

Mention the bot in the channel:

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

The agent responds in the thread. Output may vary depending on the model and instructions.

## Next steps

You can extend this agent to:

- [Deploy your application](https://mastra.ai/docs/deployment/overview) and update the Slack **Request URL** to your production endpoint
- Add more adapters (Discord, Telegram) to the same agent so it responds on multiple platforms
- Configure [multimodal content](https://mastra.ai/docs/agents/channels) to let your agent process images, video, and audio shared in chat
- Add [tools](https://mastra.ai/docs/agents/using-tools) to give the agent access to external APIs and data

Learn more:

- [Channels overview](https://mastra.ai/docs/agents/channels)
- [Studio](https://mastra.ai/docs/studio/overview)
- [Deployment overview](https://mastra.ai/docs/deployment/overview)
- [Chat SDK adapter docs](https://chat-sdk.dev)