Skip to content

fix(discord): support least-privilege bot permissions without Administrator#24

Merged
FaiThiX merged 1 commit intomasterfrom
feat/fix-bot-permissions
Mar 16, 2026
Merged

fix(discord): support least-privilege bot permissions without Administrator#24
FaiThiX merged 1 commit intomasterfrom
feat/fix-bot-permissions

Conversation

@FaiThiX
Copy link
Owner

@FaiThiX FaiThiX commented Mar 16, 2026

Summary

This PR removes the need to run the bot with Administrator and makes the Discord channel setup flow more reliable when using a minimal permission set.

The main issue was that the bot could create categories/channels and send messages, but it failed when applying channel/category permission overwrites. This PR updates the setup flow so the bot can safely work with explicit Discord permissions instead of relying on Administrator.

What Changed

  • Added explicit bot permission overwrites so the bot does not lock itself out of its own channels.
  • Created categories and text channels with their intended parent/overwrites during creation, instead of relying on a fragile create-then-fix flow.
  • Updated channel parent handling to use await and lockPermissions: false to avoid overwrite conflicts during setup.
  • Added recovery logic for stored channel IDs that exist but are no longer usable by the bot.
  • Improved setup logging so permission-related failures are now visible at the exact API call that failed.

Why

The previous setup could fail in partially configured guilds because:

  • the bot was able to create channels,
  • but failed when updating permission overwrites,
  • and in some cases could also end up with broken parent/permission sync behavior.

With this change, the bot now works correctly with a proper minimal permission set and no longer requires Administrator.

Required Bot Scopes

  • bot
  • applications.commands

Required Bot Permissions

These permissions are required for normal full operation with the current codebase:

  • View Channels
  • Manage Channels
  • Manage Roles
  • Send Messages
  • Embed Links
  • Attach Files
  • Read Message History
  • Manage Messages

Optional Bot Permissions

These are only needed if the related features are used:

  • Mention Everyone
    Required for @everyone / @here notification features.
  • Change Nickname
    Required if the bot should set/update its server nickname on startup.
  • Connect
    Required for voice channel features.
  • Speak
    Required for voice playback features.
  • Send TTS Messages
    Required for Discord TTS output.

Not Required

The bot does not require:

  • Administrator
  • Kick Members
  • Ban Members
  • Manage Webhooks
  • Manage Guild
  • thread permissions
  • moderation/timeouts permissions

Result

The bot can now be installed with a least-privilege permission model while still supporting channel creation, overwrite management, embeds, attachments, and normal setup automation.

@FaiThiX FaiThiX merged commit 1ddad14 into master Mar 16, 2026
4 checks passed
@FaiThiX FaiThiX deleted the feat/fix-bot-permissions branch March 18, 2026 12:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant