Skip to Content
IntegrationsSlack Integration

Slack Integration

Connect your Hatcher agent to Slack so it can respond to messages and mentions in your workspace channels.

Legacy custom bots (the old xoxb- tokens from the “Custom Integrations” page) were discontinued in March 2025. You must create a proper Slack App. If you have old bot tokens from the legacy system, they no longer work.

Prerequisites

  • A Slack workspace where you have permission to install apps
  • A Hatcher agent already created (Getting Started)
  • Slack integration is free on all Hatcher plans

Setup

Create a Slack App

  1. Go to https://api.slack.com/apps 
  2. Click Create New App
  3. Choose From scratch
  4. Enter an app name (e.g., “Hatcher Agent”) and select the workspace to install it in
  5. Click Create App

Slack’s developer documentation is migrating to https://docs.slack.dev . Some links may redirect between the old and new sites.

Configure Bot Token Scopes

  1. In your app’s settings, go to OAuth & Permissions in the left sidebar
  2. Scroll down to Bot Token Scopes
  3. Click Add an OAuth Scope and add the following:
ScopePurpose
chat:writeSend messages in channels
channels:readView basic channel info
channels:historyRead message history in public channels
app_mentions:readReceive events when the bot is @mentioned
groups:readView basic info about private channels (optional)
groups:historyRead messages in private channels (optional)
im:historyRead direct messages (optional)

At minimum, you need chat:write, channels:read, channels:history, and app_mentions:read.

Install the App to Your Workspace

  1. Scroll up on the OAuth & Permissions page
  2. Click Install to Workspace
  3. Review the permissions and click Allow
  4. Copy the Bot User OAuth Token — it starts with xoxb-
xoxb-1234567890123-1234567890123-ABCdefGHIjklMNOpqrSTUvwx

If you add more scopes later, you’ll need to reinstall the app to your workspace for the new scopes to take effect.

Subscribe to Bot Events

  1. Go to Event Subscriptions in the left sidebar
  2. Toggle Enable Events to On (Socket Mode handles delivery, so you don’t need a Request URL)
  3. Scroll down to Subscribe to bot events and add:
EventDescription
app_mentionWhen someone @mentions your bot
message.channelsMessages in public channels the bot is in
message.groupsMessages in private channels (optional)
message.imDirect messages to the bot (optional)
  1. Click Save Changes

Generate an App-Level Token for Socket Mode

  1. Go to Basic Information in the left sidebar
  2. Scroll down to App-Level Tokens
  3. Click Generate Token and Scopes
  4. Name it (e.g., “hatcher-socket”), add the connections:write scope, and click Generate
  5. Copy the token — it starts with xapp-

Enable Socket Mode

  1. Go to Socket Mode in the left sidebar
  2. Toggle Enable Socket Mode to On

Configure in Hatcher

  1. Go to your Hatcher Dashboard
  2. Navigate to My Agents and select your agent
  3. Open the Integrations tab
  4. Find Slack and click Configure
  5. Paste your Bot User OAuth Token (xoxb-...)
  6. Paste your App-Level Token (xapp-...)
  7. Click Save

Restart your agent

Click Restart to apply the configuration.

Invite the bot to a channel

In Slack, go to the channel where you want the bot to respond and type:

/invite @YourBotName

Or click the channel name → Integrations → Add apps.

Test it

Mention your bot in the channel (e.g., @HatcherAgent what's the price of SOL?). It should respond.

Channel Access

Your bot can only see and respond in channels it has been invited to. To add it to a channel:

  • Use /invite @BotName in the channel
  • Or go to the channel settings → Integrations → Add apps

Socket Mode

Hatcher uses Socket Mode for Slack, which means your agent connects to Slack via a WebSocket rather than requiring a public HTTP endpoint. This is simpler and more reliable.

To enable Socket Mode, you need an App-Level Token in addition to the Bot Token:

  1. In your Slack app settings, go to Basic Information
  2. Scroll down to App-Level Tokens
  3. Click Generate Token and Scopes
  4. Give it a name (e.g., “hatcher-socket”) and add the connections:write scope
  5. Click Generate
  6. Copy the token — it starts with xapp-

Then in Hatcher, configure both tokens:

  • Bot Token (xoxb-...) — for sending messages and API calls
  • App Token (xapp-...) — for Socket Mode connection

With Socket Mode enabled, you do not need to configure Event Subscriptions with a Request URL. Slack delivers events directly over the WebSocket connection.

Troubleshooting

Bot doesn’t respond to messages

  1. Check scopes. Make sure you added at least chat:write, channels:read, channels:history, and app_mentions:read. If you added scopes after installing, reinstall the app.
  2. Check event subscriptions. Make sure app_mention and/or message.channels are subscribed.
  3. Invite the bot to the channel. The bot can only see messages in channels it’s been invited to.
  4. Verify the agent is running in the Hatcher dashboard.

”not_authed” or “invalid_auth” error

Your bot token is invalid. Common causes:

  • Token was rotated in Slack’s admin settings
  • Token was copied with extra whitespace
  • App was uninstalled and reinstalled (generates a new token)

Fix: Go to your app’s OAuth & Permissions page, copy the current Bot User OAuth Token, update it in Hatcher, and restart.

”missing_scope” error

Your bot is trying to perform an action it doesn’t have permission for.

Fix: Go to OAuth & Permissions → Bot Token Scopes, add the missing scope, then reinstall the app to your workspace. Update the token in Hatcher if it changed.

Socket Mode not connecting

If your agent can’t connect via Socket Mode:

  • Verify the App-Level Token (xapp-...) is correct and has the connections:write scope
  • Make sure Socket Mode is enabled in the app settings
  • Check that your agent is running in the Hatcher dashboard

Bot responds multiple times

This usually means multiple instances of the bot are running, or event subscriptions are duplicated. Check that you only have one active Hatcher agent with this Slack token.

Last updated on
Make (Integromat) IntegrationTelegram Integration