Skip to main content

​
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

1

Create a Discord Application

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

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

Copy the bot token

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

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

Set the bot token in FERAL

export FERAL_DISCORD_BOT_TOKEN="MTEyMzQ1Njc4OTAxMjM0NTY3OA..."
6

Configure channel restrictions (optional)

{
  "channels": {
    "discord": {
      "enabled": true,
      "allowed_channel_ids": ["1123456789012345678"],
      "allowed_guild_ids": ["9876543210987654321"],
      "respond_to_mentions_only": false,
      "prefix": "!feral"
    }
  }
}
SettingDefaultDescription
allowed_channel_ids[] (all)Restrict to specific text channels
allowed_guild_ids[] (all)Restrict to specific servers
respond_to_mentions_onlyfalseOnly respond when @mentioned
prefixnullCommand prefix (e.g., !feral status)
7

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:
IntentRequiredPurpose
GUILDSYesTrack servers and channels
GUILD_MESSAGESYesReceive channel messages
MESSAGE_CONTENTYesRead message text (privileged)
DIRECT_MESSAGESYesReceive DMs
GUILD_MEMBERSNoMember-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

TriggerBehavior
DM to botAlways responds
@FERAL in channelResponds with full context
Prefix command (!feral ...)Responds if prefix is configured
Any message in allowed channelResponds if respond_to_mentions_only is false
FERAL formats responses using Discord embeds for rich output — charts, health summaries, and SDUI cards are rendered as embedded messages.

​
Slash Commands

FERAL automatically registers these slash commands when it connects:
CommandDescription
/feral ask <question>Ask FERAL anything
/feral statusShow brain and hardware status
/feral briefingGet your morning briefing
/feral healthLatest health metrics

​
Troubleshooting

Verify that Message Content Intent is enabled in the developer portal. Without it, the bot receives events but message content is empty.
Re-generate the OAuth2 invite URL with the correct scopes (bot, applications.commands) and re-invite.
FERAL includes automatic rate limit handling. If you see 429 errors in logs, reduce message frequency or restrict to fewer channels.