Slack Integration

Atlas integrates with Slack via a slash command (/atlas) and threaded follow-ups. Ask questions in any channel, get answers with formatted data tables, and continue the conversation in a thread.

Setup Modes

Both modes require SLACK_SIGNING_SECRET for request signature verification.

Single-Workspace Setup (Self-Hosted)

The simplest setup -- no OAuth flow, no database storage for tokens.

1. Create a Slack App

Go to api.slack.com/apps and create a new app from scratch.

2. Configure Scopes

Under OAuth & Permissions, add these Bot Token Scopes:

• commands -- Register slash commands
• chat:write -- Post messages
• app_mentions:read -- Read mentions (for thread follow-ups)

3. Create the Slash Command

Under Slash Commands, create a new command:

• Command: /atlas
• Request URL: https://your-api-host/api/v1/slack/commands
• Description: Ask a data question

4. Enable Events

Under Event Subscriptions:

• Request URL: https://your-api-host/api/v1/slack/events
• Subscribe to bot events: message.channels, message.groups

5. Install and Configure

Install the app to your workspace, then copy the Bot User OAuth Token and Signing Secret:

# .env — copy these from your Slack app's settings page
SLACK_BOT_TOKEN=xoxb-your-bot-token        # OAuth & Permissions → Bot User OAuth Token
SLACK_SIGNING_SECRET=your-signing-secret    # Basic Information → Signing Secret

Multi-Workspace OAuth Setup (Self-Hosted)

For distributing Atlas to multiple Slack workspaces. Requires an internal database (DATABASE_URL) to store per-workspace bot tokens.

1. Configure OAuth

In your Slack app settings, under OAuth & Permissions:

• Redirect URL: https://your-api-host/api/v1/slack/callback

2. Set Environment Variables

# .env — OAuth credentials from your Slack app settings
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_SIGNING_SECRET=your-signing-secret
DATABASE_URL=postgresql://...        # Required — stores per-workspace bot tokens

3. Install Flow

Direct users to https://your-api-host/api/v1/slack/install. This redirects to Slack's OAuth authorize page. After approval, the callback stores the bot token in the slack_installations table.

How It Works

Slash Command

/atlas What was last month's revenue?

1. Slack sends the command to POST /api/v1/slack/commands
2. Atlas verifies the request signature (HMAC-SHA256, 5-minute timestamp window)
3. Atlas immediately acknowledges within 3 seconds (Slack requirement)
4. In the background, Atlas posts a "Thinking..." message, runs the agent, and updates the message with the formatted response

Thread Follow-ups

When a user replies in a thread started by Atlas:

1. Atlas receives the message via the Events API
2. Loads the conversation history from the original thread
3. Runs the agent with the full conversation context
4. Posts the response in the same thread

This provides multi-turn conversations within Slack threads.

Action Approvals

When the action framework is enabled and a query produces pending actions, Atlas posts approval buttons visible only to the requesting user. Clicking Approve or Deny triggers POST /api/v1/slack/interactions.

Message Formatting

Atlas formats responses using Slack Block Kit:

• Answer text -- The agent's narrative response
• SQL -- The executed query in a code block
• Data table -- Column-aligned text table (max 20 rows displayed, with a "Showing X of Y" note)
• Metadata -- Steps taken, tokens used

Block Kit limits: max 50 blocks per message, max 3,000 characters per text block.

Environment Variables

See Environment Variables for the full reference.

Deployment Notes

• The API must be accessible over HTTPS for Slack to deliver events and commands
• Slash commands have a 3-second response deadline -- Atlas acknowledges immediately and processes asynchronously
• Rate limiting is per Slack user per team for commands, and per team for thread follow-ups
• Error messages sent to Slack are scrubbed to prevent leaking connection strings, API keys, or stack traces
• Without an internal database (DATABASE_URL), thread conversation mappings and OAuth tokens cannot be persisted. Single-workspace mode with SLACK_BOT_TOKEN still works, but thread follow-ups won't have conversation history

Troubleshooting

Events not being delivered -- Verify the Request URL in your Slack app settings is HTTPS and publicly reachable. Slack retries failed deliveries but will disable the subscription after repeated failures.

OAuth callback fails -- Ensure the Redirect URL in your Slack app settings matches https://your-api-host/api/v1/slack/callback exactly. Check that DATABASE_URL is set (required for storing OAuth tokens).

Bot doesn't respond in threads -- The bot needs message.channels and message.groups event subscriptions. Also verify DATABASE_URL is set for conversation history persistence.

See Troubleshooting for general diagnostic steps.