Slack

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

Create a Slack App

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

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-).

Configure Bot Token Scopes

Go to OAuth & Permissions and add these Bot Token Scopes:

Scope	Purpose
`chat:write`	Send messages
`channels:read`	List public channels
`channels:history`	Read channel messages
`groups:read`	List private channels the bot is in
`groups:history`	Read private channel messages
`im:read`	Read DMs
`im:history`	Read DM history
`im:write`	Send DMs
`app_mentions:read`	React to @mentions
`files:read`	Read shared files

Enable Event Subscriptions

Go to Event Subscriptions → toggle on. Under Subscribe to bot events, add:

message.channels
message.groups
message.im
app_mention

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-).

Set FERAL tokens

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

{
  "channels": {
    "slack": {
      "enabled": true,
      "bot_token": "xoxb-...",
      "app_token": "xapp-..."
    }
  }
}

Configure channel behavior (optional)

{
  "channels": {
    "slack": {
      "enabled": true,
      "allowed_channels": ["C01ABCDEF", "C02GHIJKL"],
      "respond_to_mentions_only": true,
      "thread_replies": true
    }
  }
}

Setting	Default	Description
`allowed_channels`	`[]` (all)	Restrict to specific channel IDs
`respond_to_mentions_only`	`true`	Only respond when @mentioned in channels
`thread_replies`	`true`	Reply in threads instead of top-level

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

Context	Trigger	Response Style
DM	Any message	Full conversational response
Channel	`@FERAL` mention	Threaded reply (if `thread_replies` is on)
Channel	Direct 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

Bot appears offline in Slack

Check that FERAL_SLACK_APP_TOKEN is set correctly. The app-level token powers Socket Mode. Run feral doctor to validate.

not_in_channel error

The bot must be invited to each channel. Use /invite @FERAL in the target channel.

Missing scopes error

Re-visit OAuth & Permissions and add any missing scopes, then reinstall the app to your workspace.

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Overview

Setup

How It Works

DM vs. Channel Behavior

Troubleshooting

​Overview

​Setup

​How It Works

​DM vs. Channel Behavior

​Troubleshooting

Overview

Setup

How It Works

DM vs. Channel Behavior

Troubleshooting