---
title: Slack
description: Connect your AI agent to Slack workspaces.
---

## Setup

```bash
pnpm add @slack/bolt
```

## Create Your Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
2. Choose **From scratch**, give it a name, select your workspace
3. **Enable Socket Mode** (sidebar → Socket Mode → toggle on):
   - Generate an app-level token with `connections:write` scope
   - Save it as `SLACK_APP_TOKEN=xapp-...`
4. **Add Bot Scopes** (sidebar → OAuth & Permissions → Scopes):
   - `chat:write` — send messages
   - `app_mentions:read` — detect @mentions
   - `im:history` — read DM history
   - `im:read` — access DMs
   - `im:write` — send DMs
5. **Subscribe to Events** (sidebar → Event Subscriptions → toggle on):
   - Bot events: `message.im`, `app_mention`
6. **Install to Workspace** (sidebar → Install App → Install):
   - Copy "Bot User OAuth Token" → save as `SLACK_BOT_TOKEN=xoxb-...`
7. Copy "Signing Secret" from Basic Information → save as `SLACK_SIGNING_SECRET=...`

## Usage

```typescript
import { slackChannel } from '@cogitator-ai/channels';

const slack = slackChannel({
  token: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  appToken: process.env.SLACK_APP_TOKEN!,
});
```

## Configuration

```typescript
interface SlackConfig {
  token: string;
  signingSecret: string;
  appToken?: string;
  socketMode?: boolean;
  port?: number;
}
```

## Features

| Feature | Support |
|---------|---------|
| DMs | ✅ |
| Channel messages | ✅ (via @mention) |
| Socket Mode | ✅ (no public URL needed) |
| HTTP Mode | ✅ (needs public endpoint) |
| Streaming (edit) | ✅ via `chat.update` |
| File uploads | ✅ via `files.uploadV2` |
| Typing indicator | ⚠️ (no-op, Slack API doesn't support it) |
| Markdown | ✅ Slack mrkdwn format |

## Socket Mode vs HTTP

- **Socket Mode** (recommended for dev): no public URL needed, uses WebSocket. Requires `appToken`.
- **HTTP Mode**: set `socketMode: false` and provide a `port`. Needs a publicly accessible URL.

## Tips

- Socket Mode is the simplest way to get started — no ngrok or public server needed
- You need 3 tokens total: Bot Token (`xoxb-`), Signing Secret, and App Token (`xapp-`)
- Reinstall the app after changing scopes
- The bot must be invited to channels to respond there (DMs work automatically)
