discord

title	Discord Configuration
category	productivity
description	Skills for configuring and managing Discord integrations, webhooks, and automation
name	discord

Discord Bot Configuration for Hermes Gateway

Environment Variables (.env)

Required variables in ~/.hermes/.env:

• DISCORD_BOT_TOKEN — Token from Discord Developer Portal > Your App > Bot > Copy Token
• DISCORD_ALLOWED_USERS — Comma-separated Discord user IDs (or usernames). If empty, all users are allowed
• DISCORD_FREE_RESPONSE_CHANNELS — Comma-separated channel IDs where bot responds without @mention

Example:

DISCORD_BOT_TOKEN=MTQ4OD...Mr7Q
DISCORD_ALLOWED_USERS=jacobm1978
DISCORD_FREE_RESPONSE_CHANNELS=1488962442460528853,1488962442460528854

Config.yaml Settings (discord section)

In ~/.hermes/config.yaml under discord::

• require_mention: true — Bot only responds when @mentioned (in non-free channels)
• free_response_channels: '' — Channel IDs for mention-free responses (also needs DISCORD_FREE_RESPONSE_CHANNELS env var set — the gateway reads the env var, not just config.yaml)
• auto_thread: true — Auto-create a thread per conversation on @mention
• reactions: true — Bot adds emoji reactions (👀 processing, ✅ success, ❌ failure)

Critical Finding: Free Response Channels Need BOTH

The free_response_channels setting in config.yaml is NOT enough. The gateway code at gateway/platforms/discord.py line 2001 reads os.getenv("DISCORD_FREE_RESPONSE_CHANNELS", ""). You must also set the env var.

How the Message Flow Works

1. on_message receives all Discord messages
2. Checks DISCORD_ALLOWED_USERS — if set and user not in list, message is silently dropped
3. Checks bot self-messages (ignored), system messages (ignored), other bots (filtered by DISCORD_ALLOW_BOTS)
4. Checks DISCORD_IGNORE_NO_MENTION (default true) — if message mentions someone else but not the bot, it's ignored
5. If require_mention is true AND channel not in free list AND not a bot thread, @mention is required
6. Auto-threading creates new threads for @mentions
7. Message is routed to the agent

Username Resolution

Non-numeric entries in DISCORD_ALLOWED_USERS (like "jacobm1978") are resolved to numeric IDs at bot startup via guild member lookup. This requires:

• members intent enabled in Discord Developer Portal
• Bot must be in the same guild as the user
• Look at startup logs for: [Discord] Resolved 'username' -> ID (user#0000)

If resolution fails silently, the user will be rejected. To debug, temporarily set DISCORD_ALLOWED_USERS= (empty) to allow all users.

Starting the Gateway

Systemd may not be available. Use:

hermes gateway run    # foreground mode (works everywhere)

For background: run in a background terminal process.

Getting Discord IDs

Enable Developer Mode in Discord settings, then right-click users/channels/guilds > Copy ID.

Common Problem: Bot Connected But Not Responding

The bot can be authenticated and "connected" (shows in logs as [Discord] Connected as Bot#0000) but still NOT respond to any messages if it is not actually joined to the server/chat where messages are sent.

Signs the bot is not in the server:

• Gateway logs show "Connected" and "Synced slash commands" but NO message events at all (no "message received", no "allowed user check", nothing)
• approximate_guild_count: 0 when querying the bot's application info

How to Invite a Bot to a Server (Without Navigating the Developer Portal)

If you have the DISCORD_BOT_TOKEN, you can look up the bot's Application ID and construct the invite URL yourself:

# Step 1: Look up the Application ID from the bot token
curl -s -H "Authorization: Bot YOUR_BOT_TOKEN" https://discord.com/api/v10/applications/@me | grep '"id"' | head -1

This returns the id field. Use it to build the OAuth2 invite URL:

https://discord.com/oauth2/authorize?client_id=APPLICATION_ID&scope=bot+applications.commands&permissions=3200

Open that URL in a browser, select the server, and click Authorize.

Permissions value 3200 grants: Send Messages, Read Message History, View Channels, Embed Links.

Important: Human invite links (discord.gg/...) cannot be used by bots

• Bots are not Discord user accounts and cannot click/accept server invites
• Bots must be added via the OAuth2 application authorization flow

After changing .env or config.yaml:

1. Kill the gateway process (Ctrl+C or kill PID)
2. Run hermes gateway run
3. Check logs: tail -f ~/.hermes/logs/gateway.log