Skip to main content
GiselleBot

Permissions System

As soon as you invite the bot to your server, a few modules will be immediately available to all of your members. The restricted modules, on the other hand, will only be available to server managers (users with "Manage Server" permissions).

This module lets server managers authorize server members to use any of the bot's modules, on a module basis.

Note

Configuring this module (which roles/users can use which modules, and channel overrides) has moved to your server's Command Permissions page on the dashboard - see the Roles and Users Permissions and Channel Overrides sections below.

Each module can be enabled for a list of roles and/or individual users, so that authorized members will immediately have access to all of the commands contained in said module. Discord permissions checks (e.g. "Manage Messages") will still apply and take precedence, where applicable. The list of Discord permissions needed to run each command is written below each command within this documentation.

Modules can also be completely disabled within a server, which means not even server managers will be able to use them unless the module is re-enabled from the dashboard (see the Roles and Users Permissions section below).

Before role permissions are checked, another layer of permissions are checked for non-manager members: channel overrides. Each module can be locked to be only run within a specified set of channels (whitelist mode) or outside a specified set of channels (blacklist mode). See the Channel Overrides section below.

Note

A small subset of commands ignores these limitations and can always be run by everyone in the server, as long as the whole module isn't disabled. These commands have a dedicated way of setting their permissions, which is usually specified in the dedicated module page. This particular set contains the following commands (now under their new names, where they were ported to a slash command): emojisubmit, /rules, /submit, /selfroles list, /role get and /role drop. !verbose and !bid used to be part of this set too, but have both since been retired - see Permissions Debugging below.

See also

Full migration mapping for these commands: Migration Guide.

How Permission Checks Work

This is the part that trips people up: "permissions" means at least four different things depending on where you're looking - Discord's own per-server command permissions, this dashboard's Command Permissions page, a plain Discord permission (like "Manage Roles") that a specific command checks for on its own, and, for a few commands, a hand-written rule that isn't a Discord permission at all. They're independent systems, layered on top of each other, and a command only runs if it clears every layer that applies to it. Understanding the order below is the key to answering "why can/can't this role use this command."

Layer 1: Discord's own command permissions (Integrations)

Every GiselleBot slash command is published with a default required permission (for example, /restrict and /case both default to "Moderate Members", /ban defaults to "Ban Members"). By default, only members holding that permission even see the command in Discord's / picker.

A server admin can override this per command, per role, and per channel from Discord's own UI - Server Settings -> Integrations -> GiselleBot - independently of anything on this dashboard. This is entirely Discord's feature, not GiselleBot's: the bot has no visibility into it and no way to configure it from the dashboard.

Note

This is the layer that lets you, say, hide /ban from a role that technically has Ban Members, or show /restrict to a role that doesn't have Manage Roles yet. But showing someone a command here does not mean the bot will let them actually use it - Layers 2 and 3 below still apply once the command actually runs. Discord's Integrations page only ever controls visibility and invocability, never what the bot does with the interaction after that.

Layer 2: Module authorization (this dashboard's Command Permissions page)

Once a member can invoke a command at all, GiselleBot checks whether they're allowed to use the module that command belongs to (moderation, administration, util, and so on - see Default Module Permissions below for the full list and each module's default). This is what this dashboard page configures, in this order:

  1. Is the module disabled entirely? If so, nobody can use it - not even server managers - until it's re-enabled from the dashboard.
  2. Channel overrides (non-manager members only): a module can be locked to only work inside a set of channels (whitelist) or outside a set of channels (blacklist). See Channel Overrides below. A server manager always bypasses this.
  3. Role/user authorization: is the invoking member a server manager (Manage Server), or explicitly authorized for this module by role or by user ID? If neither, and the command isn't in the always-allowed set noted above, the module denies them here.

This layer is per-module, not per-command - authorizing a role for the moderation module gives it every command in that module (/warn, /ban, /case, /restrict, ...), not a subset. See Command-Level Permissions below for why that's a real limitation and what it would take to change.

Layer 3: In-command Discord permission checks

Passing Layer 2 only proves someone is authorized for the module - it does not check whether they actually hold any particular Discord permission. Many commands add that check themselves, on top of everything above: they read the invoking member's real Discord permissions (computed from their roles, exactly like Discord itself would) and require a specific one, independently of both Layer 1's picker-visibility permission and Layer 2's module authorization.

This is why /restrict's six channel/images subcommands need Manage Roles and its two channel mute/channel unmute subcommands need Moderate Members even though the whole command's Layer-1 picker permission is just "Moderate Members" - the picker permission only has to be a permission that makes sense to show the command for, not the exact permission every subcommand actually enforces. Every command's own required permission is listed in its "Permissions Needed" section elsewhere in this documentation.

Note

Layer 3 is fixed per command in the bot's code today - it is not configurable from this dashboard, and a Layer-1 override in Discord's Integrations settings does not relax it. Granting a role visibility into /restrict without also granting it Manage Roles will let that role open the command but not complete any subcommand that needs Manage Roles - they'll get an in-Discord error naming the missing permission instead. See Command-Level Permissions below.

Layer 4: Command-specific business rules

A small number of commands layer one more rule on top of Layers 1-3, for actions treated as more sensitive than "can use this module" or "holds this permission" alone would justify. The clearest example is /case, and its three subcommands each draw the line slightly differently:

  • /case show has no Layer 4 rule at all - any moderator authorized for the module can view any case.
  • /case delete and /case restore require Manage Server to touch a case another moderator (or an admin) issued by hand. The one exception is a bot-issued case (an AutoModerator action) - any authorized moderator can delete/restore those, since nobody "owns" a case the bot filed itself.
  • /case edit is the strictest and the odd one out: it requires Manage Server, or being the case's own original issuing moderator - a moderator can always edit a case they personally issued, even without Manage Server, but (unlike delete/restore) cannot edit someone else's human-issued case on module access alone.

A moderator with full access to the moderation module and Moderate Members cannot delete, restore, or edit a case someone else opened by hand unless they also hold Manage Server - the sole exception is editing (not deleting or restoring) a case they issued themselves, which needs no extra permission.

Like Layer 3, this is fixed in the bot's code - there's no dashboard setting or Discord override that loosens or tightens it per server.

Worked example: /restrict images (imageban)

Putting all four layers together for one concrete command:

  1. Layer 1: the member needs to see /restrict in the picker - either by holding Moderate Members (the command's default), or because a server admin granted them an override in Discord's Integrations settings.
  2. Layer 2: the moderation module must be enabled, the invoking channel must pass any channel override, and the member must be a server manager or explicitly authorized for moderation.
  3. Layer 3: the member's actual Discord permissions must include Manage Roles - this is checked in-bot regardless of what Layer 1 shows them.
  4. Layer 4: none for this particular command - it doesn't add anything beyond the three checks above.

All three applicable layers have to pass. Miss any one and the command stops with an explanation of which check failed.

Command-Level Permissions

Everything above authorizes modules, not individual commands - so today there's no way to, say, let a role use /warn but not /ban, even though both live in the moderation module, short of the hard-coded Layer 3/4 checks a specific command happens to already have. Finer-grained, per-command (and eventually per-subcommand) authorization - configurable the same way module permissions are today - is a known gap, tracked for future work. Until then, the closest available levers are Layer 1's per-command Discord override (visibility only, not enforcement) and, where a command already has one, its own Layer 3/4 requirement.

Default Module Permissions

Here's the list of modules that are automatically enabled for everyone as soon as the bot joins a server and those that are locked to server managers only, until a server manager explicitly authorizes more roles/users for them from the Command Permissions page. Internal module permissions and in-Discord permissions checks (e.g. "Manage Messages") still apply either way.

Available to everyone

Manager-only by default

Everything else - administration (Server Administration), automoderator (Server Moderation (AutoModerator)), custreact (Custom Reactions), emojisub (Emoji Submissions), forms (Forms Builder), giveaway (Giveaway Campaigns), greets (Welcome & Goodbye), moderation (Server Moderation (Manual)), permissions (this module), reddit (Reddit Connector), rss (RSS Reader), send (Send), tools (Clock & Member Count Channels), and verification (Verification) - starts locked to server managers (Manage Server) until explicitly opened up.

Permissions Debugging

Note

!verbose has been retired with no direct replacement. Denials are now shown to you directly in Discord (as an ephemeral reply) instead of by DM, so there's no longer a separate mode to toggle - and the "did you mean" suggestion for a mistyped command is gone along with it.

Roles and Users Permissions

Note

Viewing a server's module permissions (the old !permshow/pes and !permshowmod/pesm), and enabling, disabling or fully toggling a module for specific roles/users (the old !permenablemod/peem, !permdisablemod/pedm and !permtogglemod/petm), are now configured from your server's Command Permissions page on the dashboard.

Applying permissions to several modules at once

Setting up the same roles/users/channels on more than one module no longer means repeating the same edit once per module:

  • From a single module's permissions page, Apply to other modules... copies whatever is currently shown (saved or not) onto any other modules you pick.
  • From the module list page, select several modules' checkboxes, then Configure selected... to open one shared editor - starting from the first selected module's settings - and apply the result to all of them at once.

Either way, the module you use to configure Command Permissions itself can never be disabled, so a bulk apply that includes "disabled" simply leaves that one module enabled rather than failing the whole batch.

Channel Overrides

Note

Toggling a channel on a module's override list, and switching a module between whitelist/blacklist mode (the old !chanpermtoggle/cpt and !chanpermtogglemode/cptm), are now configured from your server's Command Permissions page on the dashboard.