hermes - 💡(How to fix) Fix [Bug]: Discord slash commands fail with "Unknown integration" when only one Installation Context is authorised

Bug Description

Slash commands fail with Unknown integration (Discord error 10003) in DMs and do not appear at all inside the guild, despite the gateway successfully registering them at startup. Regular @-mention messages to the bot work fine — only slash commands are broken.

The failure mode is non-obvious because slash command autocomplete still renders in DMs, suggesting the bot is correctly configured. The issue stems from Discord's two Installation Contexts (Guild Install and User Install) being independent authorisations — ticking both in the dev portal only declares support, it does not install the app into both. The current Discord setup guide does not call this out.

A related security gap exists in the same flow: the docs do not instruct users to disable Public Bot after installation, leaving the application discoverable and installable by anyone with the application ID.

Steps to Reproduce

1. Follow the Discord setup guide end to end
2. In the Developer Portal, toggle Public Bot ON (required for user-scope install by the app owner)
3. Under Installation → Installation Contexts, tick Guild Install only (or tick both but only complete one install pass — the failure is the same)
4. Configure permissions per the recommended additional permissions
5. Open the Discord Provided Link and complete the Guild Install flow into a target server
6. Start the Hermes gateway and confirm slash command registration succeeds in the logs
7. In the target server, type / and look for Hermes commands
8. In a DM with the bot, type / and attempt to execute any command

Expected Behavior

• Slash command autocomplete lists Hermes commands inside the guild
• Slash command autocomplete lists Hermes commands inside DMs
• Executing any slash command in either context succeeds
• The setup guide warns users that Public Bot must be toggled back OFF after install

Actual Behavior

• / autocomplete does not show Hermes commands inside the guild
• / autocomplete does show Hermes commands inside DMs
• Executing any slash command in DM returns "This interaction failed — Unknown integration" (Discord error 10003)
• Regular @-mention messages in the guild work correctly
• Gateway logs show successful slash command registration at startup with no errors or warnings
• After completing setup, Public Bot remains ON with no instruction to disable it, leaving the application discoverable by application ID

Affected Component

Gateway (Telegram/Discord/Slack/WhatsApp), Setup / Installation

Messaging Platform (if gateway-related)

Discord

Debug Report

N/A

Operating System

MacOS 26.3

Python Version

No response

Hermes Version

v12.0

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

Discord's Installation Contexts (Guild Install and User Install) are two independent authorisations. Ticking both checkboxes in the dev portal only declares that both contexts are supported — it does not install the app into both. Each context requires its own pass through the install link:

• The Guild Install authorisation adds the bot as a guild member and registers commands against the guild-install context
• The User Install authorisation adds the app to a user account and registers commands against the user-install context

When the registered command's integration_types array on Discord's side does not match a context that has actually been authorised for the invoking surface, Discord returns error 10003 (Unknown integration) on execution. Autocomplete can still render in DMs because the client resolves command metadata from the global registration before checking authorisation, which is what makes the failure mode confusing.

The security gap is independent but compounded by the same setup flow: Public Bot must be toggled ON for the app owner to complete the User Install step, but the docs never instruct users to turn it back OFF afterwards. The result is that every user who follows the current docs ends up with a discoverable, publicly-installable application unless they happen to know to disable it. While DISCORD_ALLOWED_USERS / DISCORD_ALLOWED_ROLES gates who can talk to the bot, Public Bot ON allows anyone to install the app to their own server or user account, which gives them: the ability to ping the gateway with crafted interactions, presence in their own server's member list (usable for social engineering against the bot owner), and a surface for any future Discord adapter vulnerabilities or Hermes auth bypasses.

Proposed Fix (optional)

Workaround for affected users:

1. In the Developer Portal, temporarily toggle Public Bot ON
2. Under Installation → Installation Contexts, ensure both Guild Install and User Install are ticked
3. Open the Discord Provided Link and complete the Guild Install flow — selecting the target server
4. Open the same link a second time and complete the User Install flow — selecting "Add to my apps"
5. Toggle Public Bot back OFF (existing installs persist)

No gateway restart required. After both installs, slash commands work in both contexts.

Documentation changes to Step 5: Generate the Invite URL:

1. Add a note about the dual-install requirement:

Note: If you ticked both Guild Install and User Install, you need to open the install link twice — once to install to your server, once to install to your user account. Each context is a separate authorisation. If only one is completed, slash commands will fail with "Unknown integration" in the un-installed context.

1. Add a mandatory post-install security step:

Important: After completing both installs, return to the Developer Portal and toggle Public Bot back to OFF. Your existing installs persist when Public Bot is disabled. Leaving Public Bot ON allows anyone with the application ID to install your bot to their own server or account, exposing your gateway to unsolicited interactions even though the allowlist still gates message access.

Severity

• Functional bug: Low — workaround is straightforward once understood, but high friction for first-time setup
• Security gap: Medium — every user following the current docs ends up running with Public Bot ON

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR