Slack Gateway

Prerequisites

• A Slack workspace where you have admin rights
• Docker Compose running

1. Create a Slack App

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name it Org in a Box and select your workspace

2. Configure OAuth Scopes

Under OAuth & Permissions → Bot Token Scopes, add:

channels:history    channels:read     chat:write
groups:history      groups:read       im:history
im:read             im:write          mpim:history
users:read          app_mentions:read

3. Enable Socket Mode

Under Socket Mode, toggle Enable Socket Mode on.

Generate an App-Level Token with scope connections:write. Copy the token — it starts with xapp-.

4. Subscribe to Events

Under Event Subscriptions → Subscribe to bot events, add:

message.im
message.channels
message.groups
app_mention

5. Install to Workspace

Under OAuth & Permissions → Install to Workspace. Copy the Bot User OAuth Token (starts with xoxb-).

6. Configure Environment

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
OPERATOR_USER_ID=<your-user-uuid>

7. Start the Gateway

docker compose --profile slack up -d

Usage

In any Slack channel or DM where the bot is present:

• DM the bot: just send a message
• Mention in channel: @Org in a Box summarise this thread

The bot streams responses using message edits (same UX as Slack's own streaming).

Permission requests appear as interactive Block Kit buttons — click Allow or Deny inline.

Troubleshooting

Symptom	Cause	Fix
Bot not responding	Socket not connected	Check SLACK_APP_TOKEN starts with xapp-
"not_in_channel" error	Bot not added to channel	/invite @Org in a Box
Empty responses	Missing chat:write scope	Re-install app after adding scope