Skip to main content

​
Overview

FERAL’s Slack channel uses Socket Mode (WebSocket) to receive events without exposing a public URL. The bot appears as a workspace member and can respond in channels, threads, and DMs.

​
Setup

1

Create a Slack App

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

Enable Socket Mode

In the app settings sidebar, go to Socket Mode and toggle it on. Slack generates an App-Level Token — create one with the connections:write scope.Copy the token (starts with xapp-).
3

Configure Bot Token Scopes

Go to OAuth & Permissions and add these Bot Token Scopes:
ScopePurpose
chat:writeSend messages
channels:readList public channels
channels:historyRead channel messages
groups:readList private channels the bot is in
groups:historyRead private channel messages
im:readRead DMs
im:historyRead DM history
im:writeSend DMs
app_mentions:readReact to @mentions
files:readRead shared files
4

Enable Event Subscriptions

Go to Event Subscriptions → toggle on. Under Subscribe to bot events, add:
  • message.channels
  • message.groups
  • message.im
  • app_mention
5

Install the app to your workspace

Go to Install App and click Install to Workspace. Authorize the permissions. Copy the Bot User OAuth Token (starts with xoxb-).
6

Set FERAL tokens

export FERAL_SLACK_BOT_TOKEN="xoxb-..."
export FERAL_SLACK_APP_TOKEN="xapp-..."
7

Configure channel behavior (optional)

{
  "channels": {
    "slack": {
      "enabled": true,
      "allowed_channels": ["C01ABCDEF", "C02GHIJKL"],
      "respond_to_mentions_only": true,
      "thread_replies": true
    }
  }
}
SettingDefaultDescription
allowed_channels[] (all)Restrict to specific channel IDs
respond_to_mentions_onlytrueOnly respond when @mentioned in channels
thread_repliestrueReply in threads instead of top-level
8

Restart and test

feral stop && feral start
In any allowed Slack channel, type:
@FERAL what's the status of my open tasks?

​
How It Works

Slack workspace → Socket Mode (WebSocket) → FERAL Brain → Response → Slack API
Socket Mode means FERAL doesn’t need a public URL or ngrok tunnel. The brain maintains a persistent WebSocket connection to Slack’s servers.

​
DM vs. Channel Behavior

ContextTriggerResponse Style
DMAny messageFull conversational response
Channel@FERAL mentionThreaded reply (if thread_replies is on)
ChannelDirect message (if respond_to_mentions_only is off)Top-level reply
Invite the bot to a channel with /invite @FERAL before it can read or respond there.

​
Troubleshooting

Check that FERAL_SLACK_APP_TOKEN is set correctly. The app-level token powers Socket Mode. Run feral doctor to validate.
The bot must be invited to each channel. Use /invite @FERAL in the target channel.
Re-visit OAuth & Permissions and add any missing scopes, then reinstall the app to your workspace.