Slack Bot

The Slack interaction plugin integrates Slack as a full interaction surface for Atlas. Users can ask questions via slash commands (/atlas), continue conversations in threads, approve or deny actions via Block Kit buttons, and install the bot across multiple workspaces via OAuth.

This plugin uses the routes() interface to mount Hono routes directly into the Atlas API server, and receives runtime dependencies (agent execution, conversation persistence, action approval) via config callbacks rather than importing from @atlas/api.

Installation

bun add @useatlas/slack

Prerequisites

• A Slack app configured with slash commands and Events API subscriptions
• Either a bot token (single-workspace) or OAuth credentials (multi-workspace)

Configuration

import { defineConfig } from "@atlas/api/lib/config";
import { executeAgentQuery } from "@atlas/api/lib/agent-query";
import { slackPlugin } from "@useatlas/slack";

export default defineConfig({
  plugins: [
    slackPlugin({
      signingSecret: process.env.SLACK_SIGNING_SECRET!,
      botToken: process.env.SLACK_BOT_TOKEN,
      executeQuery: executeAgentQuery,
    }),
  ],
});

For multi-workspace OAuth with conversation persistence and action approval:

export default defineConfig({
  plugins: [
    slackPlugin({
      signingSecret: process.env.SLACK_SIGNING_SECRET!,
      clientId: process.env.SLACK_CLIENT_ID!,
      clientSecret: process.env.SLACK_CLIENT_SECRET!,
      executeQuery: executeAgentQuery,
      conversations: myConversationCallbacks,
      actions: myActionCallbacks,
    }),
  ],
});

Options

Mounted Routes

The plugin mounts the following Hono routes under the plugin's base path:

Database Schema

The Slack plugin declares two tables that are auto-migrated to the Atlas internal database at boot:

• slack_installations -- Stores OAuth installations for multi-workspace mode (team_id, bot_token, installed_at)
• slack_threads -- Maps Slack threads to Atlas conversations (channel_id, thread_ts, conversation_id)

See the Slack guide for full Slack app setup instructions.

Troubleshooting

Signature verification failures

Ensure SLACK_SIGNING_SECRET matches the signing secret from your Slack app's Basic Information page. Clock skew between your server and Slack can also cause verification failures.

Bot not responding to slash commands

Verify the slash command URL in your Slack app configuration points to your Atlas API's /commands endpoint. For local development, use a tunnel service like ngrok.

OAuth callback errors

For multi-workspace OAuth, the callback URL must be registered in your Slack app's OAuth & Permissions page. Ensure it matches the route where the plugin is mounted.

Migrating to @useatlas/chat

Replace @useatlas/slack with the Chat SDK bridge plugin:

// Before:
import { slackPlugin } from "@useatlas/slack";
slackPlugin({ signingSecret: "...", botToken: "xoxb-...", executeQuery })

// After:
import { chatPlugin } from "@useatlas/chat";
chatPlugin({
  adapters: {
    slack: { botToken: "xoxb-...", signingSecret: "..." },
  },
  executeQuery,
})