Slack

Setup

pnpm add @slack/bolt

Create Your Slack App

1. Go to 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

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

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

Features

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)