Skip to main content
Slack integration uses Socket Mode, eliminating the need for a public URL or webhook configuration.

​
Features

  • ✅ Socket Mode (no public URL required)
  • ✅ Direct messages and channel mentions
  • ✅ App-level and bot tokens
  • ✅ Reaction support
  • ✅ Configurable group policy

​
Setup

1

Create a Slack app

  1. Go to Slack API
  2. Click Create New App
  3. Select From scratch
  4. Choose an app name and select your workspace
2

Enable Socket Mode

  1. In app settings, go to Socket Mode
  2. Toggle Enable Socket Mode to ON
  3. Click Generate to create an App-Level Token
  4. Add the connections:write scope
  5. Copy the token (format: xapp-...)
3

Configure OAuth & Permissions

  1. Go to OAuth & Permissions
  2. Under Bot Token Scopes, add:
    • chat:write — Send messages
    • reactions:write — Add reactions
    • app_mentions:read — Read mentions
  3. Scroll up and click Install to Workspace
  4. Authorize the app
  5. Copy the Bot User OAuth Token (format: xoxb-...)
4

Configure Event Subscriptions

  1. Go to Event Subscriptions
  2. Toggle Enable Events to ON
  3. Under Subscribe to bot events, add:
    • message.im — Direct messages
    • message.channels — Channel messages
    • app_mention — @mentions
  4. Click Save Changes
5

Enable App Home

  1. Go to App Home
  2. Scroll to Show Tabs
  3. Enable Messages Tab
  4. Check “Allow users to send Slash commands and messages from the messages tab”
6

Get your User ID (optional)

To restrict access to specific users:
  1. Click your profile in Slack
  2. Select Profile → More → Copy member ID
Or find it in the gateway logs when you message the bot.
7

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowFrom": ["YOUR_SLACK_USER_ID"],
      "groupPolicy": "mention"
    }
  }
}
8

Start the gateway

nanobot gateway
You should see:
Slack channel connected via Socket Mode
9

Test the connection

  1. Open Slack and go to your bot’s App Home
  2. Send a direct message
  3. Or @mention the bot in a channel
  4. Your bot should respond!

​
Configuration Options

​
enabled
boolean
required
Enable the Slack channel
​
botToken
string
required
Bot User OAuth Token from Slack (format: xoxb-...)Found in: OAuth & Permissions → Bot User OAuth Token
​
appToken
string
required
App-Level Token from Slack (format: xapp-...)Found in: Socket Mode → App-Level Tokens
​
allowFrom
array
required
List of Slack user IDs allowed to interact with the botExamples:
  • Single user: ["U01234ABCDE"]
  • Multiple users: ["U01234ABCDE", "U56789FGHIJ"]
  • All users: [] (empty array)
​
groupPolicy
string
default:"mention"
Controls how the bot responds in channels:
  • "mention" (default) — Only respond when @mentioned
  • "open" — Respond to all channel messages
  • "allowlist" — Restrict to specific channels
DM policy defaults to open. Set "dm": {"enabled": false} to disable DMs

​
Group Policy

​
Mention mode (default)

{
  "groupPolicy": "mention"
}
Bot only responds when @mentioned in channels.

​
Open mode

{
  "groupPolicy": "open"
}
Bot responds to all messages in channels (can be noisy).

​
Allowlist mode

{
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["C01234ABCDE", "C56789FGHIJ"]
}
Bot only responds in specific channels.

​
Disable DMs

{
  "dm": {
    "enabled": false
  }
}
Disables direct message responses completely.

​
Troubleshooting

Common issues:
  1. Socket Mode not enabled — Check Socket Mode is ON
  2. Missing scopes — Verify all required scopes are added
  3. User ID not in allowFrom — Check your Slack user ID
  4. Events not subscribed — Ensure bot events are configured
  5. App not installed — Click “Install to Workspace”
Check logs with: nanobot gateway -v
  1. Check groupPolicy setting:
    • If set to "mention", you must @mention the bot
    • Change to "open" to respond to all messages
  2. Verify bot is invited to the channel: /invite @yourbot
  3. Check bot has permission to read and write in channel
  4. Ensure message.channels event is subscribed
If Socket Mode connection fails:
  1. Verify appToken is correct (starts with xapp-)
  2. Ensure app token has connections:write scope
  3. Check botToken is correct (starts with xoxb-)
  4. Verify tokens haven’t been revoked
  5. Restart gateway: nanobot gateway
Error: “invalid_auth” or “token_revoked”Solution:
  1. Go to Slack API → Your App → OAuth & Permissions
  2. Click Reinstall to Workspace
  3. Copy the new Bot User OAuth Token
  4. Update botToken in config
  5. Restart gateway
If you see “missing_scope” errors:
  1. Go to OAuth & Permissions → Scopes
  2. Add missing bot token scopes
  3. Reinstall the app to apply new permissions
  4. Restart gateway

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-1234567890-1234567890123-AbCdEfGhIjKlMnOpQrStUvWx",
      "appToken": "xapp-1-A01234BCDEF-1234567890123-abcdefghijklmnopqrstuvwxyz123456789012345678901234567890ab",
      "allowFrom": ["U01234ABCDE"],
      "groupPolicy": "mention"
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us