Requirements

• Node.js 22 or newer
• A Discord application with a bot user
• The bot token available through exactly one external reference: an uppercase DISCORD_*_TOKEN environment variable or an absolute credential file path
• One strict non-secret configuration file or managed profile is required for operational commands; ambient environment policy is not an alternate interface
• File-backed credentials must be regular, single-link, bounded, stable while read, owned by root or the process user, and not group or world writable; a projected-secret symlink may point at such a file
• View Channels and Read Message History in every channel the connector should read
• The Message Content privileged intent enabled manually or through the reviewed application-security workflow for full message bodies, native search, announcement crossposts, native message forwarding, Components V2 planning, and static rich-embed planning; the optional content-free Gateway feed does not request it
• Exact one-to-one private-message access needs no guild permission or privileged intent because Discord exempts content in DMs with the app; the dedicated workflow still requires pinned identity, an exact ordinary-user allowlist, expected-contact acknowledgement for new sends and replies, and Discord-side delivery eligibility
• The Guild Members privileged intent enabled manually or through the reviewed application-security workflow when opt-in member listing is needed; the optional content-free Gateway feed does not request it
• Send Messages, View Channel, and Read Message History only in exact channels selected for Components V2 creation or editing; use Send Messages in Threads instead of Send Messages for exact selected threads
• Attach Files, Read Message History, and Send Messages or Send Messages in Threads only in exact channels or threads selected for attachment messages
• View Channels, Read Message History, and Send Messages only in exact forum channels selected for forum-post creation; add Manage Threads only when selecting moderated tags
• View Channel only in exact stable forums selected for forum-tag audit; add Manage Channels only when reviewed tag changes are enabled
• View Channel plus Create Public Threads only in exact text or announcement parents selected for anchored or standalone-public creation, or Create Private Threads only in exact text parents selected for standalone-private creation; anchored creation also requires Read Message History
• Add Reactions only in exact interaction channels where the bot may add its own reactions; removing its own reaction does not require that permission
• Manage Messages, View Channel, and Read Message History only in exact channels selected for reviewed reaction moderation, plus Connect for selected voice or Stage targets
• Manage Channels and View Channel only in exact direct guild channels where reviewed metadata changes will be enabled, plus Connect on exact voice or Stage targets; exact ordinary voice-channel status additionally needs Set Voice Channel Status, while Manage Channels is conditional when the connector is not connected to the exact target
• For exact channel retirement, Manage Guild at guild scope; View Channel plus Manage Channels on the target; Manage Webhooks on webhook-capable targets; and Read Message History plus Manage Threads on text, forum, and media targets
• Manage Roles and View Channel only in exact direct guild channels where permission-overwrite changes will be enabled
• Manage Webhooks and View Channel only in exact direct guild channels where credential-redacted webhook audit or reviewed creation, rename, move, or deletion will be enabled; private webhook message actions authenticate with the stored webhook credential and do not require the bot to retain Manage Webhooks
• Manage Guild only in exact guilds where capability-safe invite inventory or reviewed invite revocation will be enabled
• Create Instant Invite plus View Channel only in exact direct channels where reviewed finite invite creation will be enabled; add Manage Guild only for exact-user acceptance, and add Manage Roles plus the nonprivileged Gateway layout only for separately allowlisted persistent invite roles
• Manage Guild and Manage Roles only in exact guilds where reviewed complete onboarding replacement will be enabled
• Manage Guild only in exact Community guilds where disabled Welcome Screen inspection or reviewed complete ordered replacement will be enabled
• Manage Guild only in exact guilds where reviewed guild-profile name or description changes will be enabled; profile audit itself can report that authority as unavailable
• Manage Guild only in exact guilds where named guild-settings audit, reviewed sparse settings changes, or incident-action audit and reviewed lockdown changes will be enabled
• Administrator only as a temporary operator-managed grant in exact guilds where the connector must add the Community feature; remove it after that reviewed frontier, then retain only Manage Guild for separately allowlisted Community routing audit or changes
• Manage Guild only in exact guilds where authenticated widget-settings audit or reviewed replacement will be enabled; the selected widget channel must remain visible to @everyone
• Create Guild Expressions only in exact guilds where the bot may create emojis or stickers it owns, and Manage Guild Expressions only where it must update or delete expressions created by another user
• Application-owned emoji reads and reviewed changes use the bot token for the verified current application and require no guild permission; keep their separate local gates disabled until intentionally configured
• Reviewed application privileged-intent enablement uses the verified owner-managed bot token and requires no guild permission, but expands application-wide Discord access across every installation; keep its separate capability and toolset disabled until intentionally configured
• Create Events only in exact guilds selected for scheduled-event administration, Manage Events only when cross-owner changes are required, and the documented channel permissions for each selected stage or voice event target
• View Channel, Connect, Manage Channels, Mute Members, and Move Members only in exact Stage channels selected for lifecycle changes; add Mention Everyone only where reviewed guild-wide start notifications are intentional
• Manage Messages only in channels where deletion will eventually be enabled
• Manage Channels and View Channels only in exact guilds and parent categories where additive channel creation or guild scaffolds will be enabled
• Manage Channels only in exact guilds selected for channel-order audit or changes; a complete visible parent-category grant is sufficient for one affected child group whose complete overwrite evidence proves it, while cross-parent placement requires complete authority on both groups plus exact target View Channel and Manage Channels
• Guild-level Manage Channels plus source View Channel only in exact guilds and source channels selected for channel-clone audit or changes; the connector must also hold every permission bit present in copied overwrites, and sources containing Manage Roles overwrites remain unavailable without Administrator
• Change Nickname only in exact guilds where the connector may change or clear its own nickname through the narrow current-bot route
• Manage Nicknames only in exact guilds where the separately gated broader route may change another eligible member, with the bot's own highest role strictly above every target
• One documented member verification-bypass authorization path only in exact selected guilds: Manage Guild, Manage Roles, or all of Moderate Members, Kick Members, and Ban Members, with the bot's own highest role strictly above every target; prefer the narrowest path already justified by other selected work
• Manage Roles only in exact guilds where additive role creation, guild scaffolds, member-role changes, exact role configuration, reviewed role retirement, or reviewed role ordering will be enabled, with the bot's own highest role above every created, assignable, configurable, deletable, movable, or anchor role
• Manage Guild additionally in exact guilds selected for role-retirement dependency audit; it permits the complete invite, integration, onboarding, AutoMod, and application-command evidence pass but grants no local deletion authority by itself
• View Channel and Connect only in exact voice or Stage channels selected for exact member voice-state audit; reviewed voice changes additionally need Move Members for moves or disconnects, Mute Members for server mute changes, or Deafen Members for server deafen changes, with View Channel and Connect also proven for the target at a move destination
• View Audit Log only in guilds where privacy-minimized server audit history is needed
• Kick Members, Ban Members, or Moderate Members only in exact guilds where the corresponding member administration action will be enabled; native bulk bans additionally require Manage Guild in every separately selected bulk-ban guild

Do not grant the bot Administrator. Restrict its Discord role at the category or channel level wherever possible.

The application public key is not used by the local REST or Gateway connections. It becomes relevant only if Discord Interaction webhooks or slash commands are added later.

Canonical source: docs/reference.md