Wiki · Integrations
Discord — server and bot
When a Discord bot stays offline it is almost always the Message Content Intent. Setup, permissions and channel behaviour.
🎮
When a Discord bot stays offline, 90 % of the time the “Message Content Intent” is missing.
Discord does not hand message content to bots by default. Hermes always asks for it, and while the
switch is off in the Developer Portal Discord refuses the connection — the bot never
comes online. The second required switch is Server Members Intent (without it usernames cannot
be resolved).
1. Application and bot
1) discord.com/developers/applications → New Application (name = bot name)
2) Bot → Add Bot → copy the token (DISCORD_BOT_TOKEN)
3) Privileged Gateway Intents:
Server Members Intent → ON (required)
Message Content Intent → ON (required!)
Presence Intent → optional
4) Installation (or a manual URL): scopes “bot” + “applications.commands”
# minimum bot permissions
View Channels · Send Messages · Embed Links · Attach Files · Read Message History
# recommended extras
Create Public Threads · Send Messages in Threads
# manual invite (replace YOUR_APP_ID)
https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=309237763136
2. User IDs and access
| Setting | Meaning |
|---|---|
DISCORD_BOT_TOKEN | The bot token |
DISCORD_ALLOWED_USERS | Numeric user IDs (comma-separated). Without this and without roles Hermes denies everyone — a safe default |
DISCORD_ALLOWED_ROLES | Role IDs — anyone holding the role is authorised (handy for rotating moderator teams) |
DISCORD_ALLOWED_CHANNELS | Restrict the bot to specific channels |
DISCORD_REQUIRE_MENTION | Whether a mention is required (default yes in channels) |
DISCORD_FREE_RESPONSE_CHANNELS | Channels where the bot answers without a mention |
Copy IDs after enabling Developer Mode in Discord (User Settings → Advanced). Usernames work as a convenience but server nicknames are never matched — anyone can change those.
3. How the bot behaves
| Where | Behaviour |
|---|---|
| Direct messages | Answers everything; each DM has its own session |
| Server channels | By default only when @mentioned; otherwise it ignores the message |
| Mention-free channels | Answers continuously (good for a “work” channel); optionally one thread per top-level message |
| Threads | Replies in the same thread; thread history stays separate from the channel |
| Several people in one channel | History is kept per user by default — two people do not overwrite each other's context |
| Forum channels | Every send creates a new thread (forums accept no direct messages) |
4. Home channel and voice
# from a channel the bot is in
/sethome
# or in .env
DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"
Proactive messages go to the home channel: scheduled job results, reminders, notifications.
Discord also supports voice: incoming voice messages are transcribed, /voice tts enables
spoken replies, and the bot can join a voice channel. The voice-mode page has the details.
5. Security
🔐
Without
DISCORD_ALLOWED_USERS or DISCORD_ALLOWED_ROLES Hermes denies everyone.
That is deliberate: an authorised user gets full access to the agent's tools, and therefore to the host.
Never open the bot to a whole server just because it is convenient.| Situation | What to do |
|---|---|
| Online but not answering | No allowlist (bot denies everyone), or the message had no mention |
| Never connects at all | Message Content Intent — see the top of the page |
| Cannot resolve users | Server Members Intent is off |
| Answers in the wrong channel | Add the channel to DISCORD_FREE_RESPONSE_CHANNELS, or restrict with DISCORD_ALLOWED_CHANNELS |