Discord

Overview

FERAL’s Discord channel uses the Gateway API with WebSocket to receive messages in real time. The bot can respond to commands, mentions, and DMs across any server it’s invited to.

Setup

Create a Discord Application

Go to the Discord Developer Portal and click New Application. Name it FERAL.

Create a Bot user

In the application settings, go to Bot and click Add Bot. Under the bot settings:

Toggle Message Content Intent to ON (required to read message text)
Toggle Server Members Intent to ON (optional, for member-aware features)
Toggle Presence Intent to OFF (not needed)

The Message Content Intent is required. Without it, FERAL receives empty message bodies for non-mention messages.

Copy the bot token

Click Reset Token to generate a new token. Copy it immediately — Discord only shows it once.

Invite the bot to your server

Go to OAuth2 → URL Generator. Select scopes:

bot
applications.commands

Select bot permissions:

Send Messages
Read Message History
Embed Links
Attach Files
Use Slash Commands

Copy the generated URL and open it in your browser to invite the bot.

Set the bot token in FERAL

export FERAL_DISCORD_BOT_TOKEN="MTEyMzQ1Njc4OTAxMjM0NTY3OA..."

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "MTEyMzQ1Njc4OTAxMjM0NTY3OA..."
    }
  }
}

Configure channel restrictions (optional)

Earlier versions of this page documented allowed_channel_ids, allowed_guild_ids, respond_to_mentions_only and prefix as options here. The brain reads none of those keys. Access control for every channel lives in the shared keys below, and the defaults are fail-closed: with no allowlist and no open pairing window, the channel accepts nothing. The old table described [] as “(all)”, which is the opposite of what the code does (channels/base.py:345-362).

{
  "channels": {
    "discord": {
      "enabled": true,
      "allowed_senders": ["1123456789012345678"],
      "allowed_chats": ["9876543210987654321"],
      "pairing_window_sec": 0
    }
  }
}

Setting	Default	Description
`allowed_senders`	`[]`	Sender ids that may reach the brain. Empty means none.
`allowed_chats`	`[]`	Chat / channel ids that may reach the brain. Empty means none.
`pairing_window_sec`	`0`	Seconds to accept the next unknown sender and bind it as owner. `0` keeps the window shut.

A sender that is not allowlisted is recorded and receives no reply at all, so a stranger cannot learn whether a brain is listening (channels/base.py:345-362).

Restart and test

feral stop && feral start

In any allowed Discord channel:

@FERAL what's my heart rate?

Gateway Intents

FERAL requests these gateway intents when connecting:

Intent	Required	Purpose
`GUILDS`	Yes	Track servers and channels
`GUILD_MESSAGES`	Yes	Receive channel messages
`MESSAGE_CONTENT`	Yes	Read message text (privileged)
`DIRECT_MESSAGES`	Yes	Receive DMs
`GUILD_MEMBERS`	No	Member-aware features

If your bot is in more than 100 servers, Discord requires verification to use privileged intents. For personal use this is not an issue.

Message Handling

Trigger	Behavior
DM to bot	Always responds
`@FERAL` in channel	Responds with full context
Prefix command (`!feral ...`)	Responds if prefix is configured
Any message in an allowlisted channel	Responds

FERAL formats responses using Discord embeds for rich output — charts, health summaries, and SDUI cards are rendered as embedded messages.

Slash Commands

Earlier versions of this page listed /feral ask, /feral status, /feral briefing and /feral health as slash commands FERAL “automatically registers when it connects”. It registers none. There is no application-command registration anywhere in the brain, and the Discord gateway handler processes only MESSAGE_CREATE (channels/base.py:1150).

Talk to the bot with ordinary messages. Anything an allowlisted sender writes is forwarded to the brain as a normal turn, so there is no command vocabulary to learn — ask for status or a briefing in plain language.

Troubleshooting

Bot is online but doesn't respond

Verify that Message Content Intent is enabled in the developer portal. Without it, the bot receives events but message content is empty.

Bot not appearing in server

Re-generate the OAuth2 invite URL with the correct scopes (bot, applications.commands) and re-invite.

Rate limited by Discord

FERAL includes automatic rate limit handling. If you see 429 errors in logs, reduce message frequency or restrict to fewer channels.

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Overview

Setup

Gateway Intents

Message Handling

Slash Commands

Troubleshooting

​Overview

​Setup

​Gateway Intents

​Message Handling

​Slash Commands

​Troubleshooting

Overview

Setup

Gateway Intents

Message Handling

Slash Commands

Troubleshooting