Skip to main content
Connect Spacebot to your Slack workspace. Takes about 5 minutes. You need two tokens from a Slack app: a Bot Token (xoxb-...) and an App Token (xapp-...).

​
Step 1: Create a Slack App

1

Create the App

Go to api.slack.com/apps → Create New App → From scratch.Name it whatever you want and select your workspace.
2

Enable Socket Mode

In your Slack app settings, go to Socket Mode and toggle it on.You’ll be prompted to create an App-Level Token. Give it a name (e.g., “spacebot”) and add the connections:write scope. Click Generate.Copy the token — this is your App Token.
3

Verify Token Format

The App Token must start with xapp-. If yours starts with app- you have the wrong value. Go to Basic Information → App-Level Tokens and copy or regenerate the xapp- prefixed one.

​
Step 2: Add Bot Scopes

In your Slack app settings, go to OAuth & Permissions → scroll to Bot Token Scopes → add all of:
ScopeWhat it’s for
chat:writeSend and edit messages
reactions:writeThinking indicator
reactions:readRead reactions
channels:historyRead message history in public channels
channels:readRead public channel metadata (for channel names)
groups:historySame, for private channels
groups:readRead private channel metadata (for channel names)
im:historySame, for DMs
im:readRead DM metadata (for conversation names)
mpim:historySame, for group DMs
mpim:readRead group DM metadata (for conversation names)
users:readResolve display names
files:writeUpload file attachments
files:readRead file metadata

​
Step 3: Subscribe to Events

In your Slack app settings, go to Event Subscriptions and make sure it’s toggled on. Under Subscribe to bot events, verify these are listed (add any that are missing):
  • message.channels — public channels
  • message.groups — private channels
  • message.im — DMs
  • message.mpim — group DMs
These tell Slack which message events to send to Spacebot. Without them, the bot won’t see messages in the corresponding channel types.

​
Step 4: Install to Workspace

1

Install the App

In your Slack app settings, go to Install App → Install to Workspace → Authorize.Copy the Bot User OAuth Token — this is your Bot Token. It starts with xoxb-.
2

Invite the Bot

In Slack, go to any channel you want the bot in and run /invite @YourBotName.

​
Step 5: Add Tokens to Spacebot

config.toml
[messaging.slack]
enabled = true
bot_token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"

[[bindings]]
agent_id = "main"
channel = "slack"
You can also reference environment variables:
config.toml
[messaging.slack]
enabled = true
bot_token = "env:SLACK_BOT_TOKEN"
app_token = "env:SLACK_APP_TOKEN"
Token changes in config require a restart.

​
Verify It’s Working

Send a message in one of the channels you invited the bot to. You should see:
  1. A 🤔 reaction appear while it processes
  2. A reply from the bot
The reaction is removed once the response is complete.

​
Filtering

​
Restrict to Specific Channels

By default the bot responds in every channel it’s been invited to. To limit it, add channel IDs to your binding.
config.toml
[[bindings]]
agent_id = "main"
channel = "slack"
workspace_id = "T01234ABCDE"
channel_ids = ["C0001", "C0002"]

​
Finding Your Workspace ID

The workspace ID is the T-prefixed string in your Slack URL: 
https://app.slack.com/client/T01234ABCDE/...
                            ^^^^^^^^^^^^

​
DM Filtering

By default, all DMs are ignored. To allow specific users, add their Slack user IDs.
config.toml
[messaging.slack]
dm_allowed_users = ["U01234", "U56789"]
Permission changes hot-reload within a couple seconds — no restart needed.

​
Slash Commands

You can route Slack slash commands to specific agents.
1

Create a Slash Command

In your Slack app settings, go to Slash Commands → Create New Command.
  • Command: /ask (or any name)
  • Request URL: Leave this empty (Socket Mode handles it)
  • Short Description: “Ask the AI agent”
2

Configure Routing

config.toml
[[messaging.slack.commands]]
command = "/ask"
agent_id = "main"

[[messaging.slack.commands]]
command = "/support"
agent_id = "support-bot"
When a user types /ask question here, Spacebot routes it to the main agent.

​
Rich Messages

Slack supports rich message features:

​
Block Kit

Structured messages with sections, dividers, buttons, and select menus. Spacebot automatically converts OutboundResponse::RichMessage to Block Kit layout.

​
Ephemeral Messages

Send messages visible only to the triggering user with OutboundResponse::Ephemeral. Useful for confirmations or error messages.

​
Scheduled Messages

Schedule messages for future delivery with OutboundResponse::ScheduledMessage. Uses Slack’s native chat.scheduleMessage API.

​
Threads

Threads get their own separate conversation with isolated history. Messages in the main channel share one conversation.

​
Troubleshooting

SymptomCauseFix
invalid_auth on startupWrong app tokenMust start with xapp-, not app-
invalid_auth on API callsWrong bot tokenReinstall app, copy fresh xoxb- token
Connects then immediately dropsSocket Mode not enabledSlack app settings → Socket Mode → toggle on
Bot doesn’t respond in channelNot invited/invite @YourBot in the channel
Bot doesn’t respond to DMsDM filteringAdd user ID to dm_allowed_users
Slash command doesn’t workNot configuredAdd command to messaging.slack.commands array

​
Next Steps

Configure Permissions

Set up workspace and channel filters

Slash Commands

Route commands to different agents

Block Kit Messages

Send rich interactive messages

Build docs developers (and LLMs) love

Get started for freeTalk to us