Discord Setup

Discord is the second most common gateway platform for Hermes, and it brings something Telegram doesn't: server-based organization with channels, roles, and permissions. You can put Hermes in a #devops channel where it monitors alerts, a #coding channel where it reviews PRs, and keep it out of #general entirely. The tradeoff is more setup, Discord's bot registration requires specific gateway intents and permission scopes that trip up first-timers.

This lesson covers bot registration on the Discord Developer Portal, the Message Content Intent requirement that causes silent failures, slash commands, and channel-level access control.

What you'll learn

• Discord bots require Message Content Intent to be enabled under Bot → Privileged Gateway Intents, if you skip this, the bot connects but never sees messages
• hermes gateway setup discord walks through the token entry and tests the connection, but it can't detect a missing intent until you actually send a message
• Slash commands are registered automatically when the gateway starts, no manual command registration needed, but they take a few seconds to appear after the bot joins a server
• Channel permissions at the Discord server level gate which channels Hermes can read and write in, set these before inviting the bot, not after

The problem

Telegram works great for personal use, but it's a one-to-one or one-to-group model. Discord gives you server-based organization: you can have Hermes in multiple channels with different purposes, control who can talk to it with Discord's native role system, and use slash commands for discoverability. But Discord's bot model has a specific gotcha: the Message Content Intent. Without it enabled, your bot connects successfully, shows as online, and never responds to a single message. The gateway logs won't even show an error, the messages are never delivered to the adapter in the first place.

Options & when to use each

Setup	Good for	Costs you	When to pick it
Single channel, admin-only	A private #hermes channel where only you and trusted users can interact	Least setup, just one channel permission to configure	Personal use, testing, small teams where everyone has equal trust
Multiple channels with role gates	#devops channel gets deployment tools, #support channel gets read-only access	More Discord permission management, each channel needs its own role setup	Teams where different people need different levels of access
Public server, slash commands only	Bot responds only to slash commands, not natural language messages	Users need to know the commands exist, less conversational, more tool-like	Large servers where you don't want the bot reading every message
Voice channel integration	Hermes joins voice channels, listens and responds via TTS	Requires STT and TTS configured (covered in the Voice Mode lesson)	Hands-free environments, monitoring dashboards with audio alerts

This lesson covers the single-channel admin setup. The multi-platform lesson covers running Discord alongside Telegram.

Build it

Step 1: Create a Discord application and bot

Go to the Discord Developer Portal and click New Application. Give it a name, this is what server members see.

Navigate to Bot in the left sidebar and click Add Bot. Discord generates a bot user attached to your application.

Step 2: Enable Message Content Intent

This is the step that catches everyone. Still on the Bot page, scroll down to Privileged Gateway Intents and toggle on Message Content Intent. Save the changes.

Without this intent, Discord does not deliver message content to your bot. The bot connects to the gateway, appears online, and receives exactly zero messages. The Hermes gateway log will show the adapter initialized but no message events arriving.

While you're here, note the Token section. Click Reset Token to generate one, then copy it. You'll need it in the next step.

Step 3: Invite the bot to your server

Go to OAuth2 → URL Generator in the left sidebar. Under Scopes, select:

• bot
• applications.commands

Under Bot Permissions, select at minimum:

• Send Messages
• Read Messages/View Channels
• Read Message History
• Use Slash Commands

If you plan to use voice features later, also select Connect and Speak.

Copy the generated URL at the bottom, open it in a browser, and select the server where you want to add the bot. You need the Manage Server permission on that server to add bots.

Step 4: Connect the bot to the gateway

Run the setup wizard targeting the Discord adapter. It asks for your bot token and validates it immediately against the Discord API.

hermes gateway setup discord

Paste the bot token when prompted. The wizard tests the connection by fetching the bot's user info, if the token is wrong, it tells you immediately.

If you prefer the full wizard:

hermes gateway setup

Select Discord from the platform list and paste the token.

Step 5: Restart and verify

Configuration changes to the gateway require a process restart to take effect. Restart the gateway and inspect the logs to confirm the adapter initialized successfully.

hermes gateway restart
grep -i discord ~/.hermes/logs/gateway.log | tail -5

Look for a line confirming the Discord adapter initialized. The bot should now appear online in your server.

Step 6: Configure channel permissions

Before testing, lock down which channels Hermes can access. In your Discord server settings:

1. Right-click the bot in the member list → Roles. Or go to Server Settings → Roles and find the bot's role (Discord creates one named after your bot).
2. For each channel where you want Hermes to work, go to Channel Settings → Permissions → add the bot's role with Read Messages and Send Messages enabled.
3. For channels where you don't want Hermes, ensure the bot's role has those permissions disabled or not set.

The bot role inherits @everyone permissions by default. If @everyone can't read a channel, neither can the bot, unless you explicitly grant the bot role access.

Step 7: First message and slash commands

Send a message in an allowed channel. Hermes should respond. If it doesn't, check the Message Content Intent first, it's the cause of 90% of "bot is online but silent" problems.

Slash commands register automatically when the gateway starts. Type / in the message box and you should see Hermes commands appear. The /platforms command lists connected platforms with status. The /approve and /deny commands control gateway command approval (covered in the multi-platform lesson).

Slash commands can take up to a minute to appear after the bot first joins a server. If they don't show up, wait and try again, this is a Discord-side propagation delay, not a Hermes issue.

What goes wrong

Mistake	How you notice it	The fix
Bot is online but never responds	The bot shows as online in the member list, you send messages, nothing happens, no errors in the gateway log	Message Content Intent is disabled. Go to Discord Developer Portal → Bot → Privileged Gateway Intents → enable Message Content Intent → Save. Then restart the gateway: hermes gateway restart
"Invalid token" during setup	The wizard rejects the token immediately	You copied the wrong value. Go to Developer Portal → Bot → Reset Token, copy the new one, use it in hermes gateway setup discord
Bot responds in channels it shouldn't	Hermes replies in #general or other channels you didn't intend	The bot's role inherits @everyone permissions. Create a dedicated role for the bot, set channel-specific permissions, and remove it from the @everyone role if the bot was given one automatically
Slash commands don't appear	/ doesn't show Hermes commands, even though the bot is online and responding to messages	Wait up to 60 seconds after restart for Discord to propagate slash command registrations. If they still don't appear, check that you selected applications.commands scope when generating the invite URL. Re-invite the bot with the correct scopes if needed
Gateway crashes when Discord reconnects	Logs show Discord disconnecting and reconnecting, sometimes causing a full gateway restart	Discord periodically disconnects bots for gateway maintenance. Hermes handles reconnection, but if the gateway process itself crashes, check ~/.hermes/logs/gateway.log for the specific error. A bad platform config for another platform can crash the entire gateway, not just the offending platform

Confirm it worked

Verify the setup by checking the gateway status and testing the integration from Discord itself. Run these checks to ensure the bot is online and responding to commands.

# 1. Verify the gateway is running with Discord connected
hermes gateway status
grep -i "discord.*initialized" ~/.hermes/logs/gateway.log

# 2. Send a real task from Discord
# In the allowed channel, type:
# "List the last 10 lines of the gateway log and check
#  for any errors since the last restart."

# 3. Verify Hermes read the log file and reported back with
#    actual log contents, not a generic message

# 4. Test a slash command
# Type: /platforms
# Hermes should respond with connected platforms and status

# 5. Verify channel permissions are working
# Try sending a message from a channel where the bot doesn't
# have permissions, it should be silent there

If step 2 returns actual log contents from your machine and step 4 shows both Discord and Telegram (if you set it up) as connected, Discord is working end to end. You now have a second platform running through the same gateway process.

Next: Multi-Platform & Approval Controls , running both platforms simultaneously, per-platform tool controls, and the gateway slash commands that keep you in control.