Discord's permission system
Discord permissions are stored in a 53-bit integer and calculated using bitwise operations. If you want to dive deeper into what's happening behind the curtains, check the Wikipediaopen in new window and MDNopen in new window articles on the topic.
In discord.js, permission bit fields are represented as either the decimal value of said bit field or its referenced flags. Every position in a permissions bit field represents one of these flags and its state (either referenced
1 or not referenced
Before we get into actually assigning permissions, let's quickly go over the method Discord uses to determine a guild member's final permissions:
- Take all permissions for all roles the guild member has and add them up.
- Apply all denies for the default role (
- Apply all allows for the default role (
- Apply all denies for all additional roles the guild member has at once.
- Apply all allows for all additional roles the guild member has at once.
- Apply all denies for the specific guild member if they exist.
- Apply all allows for the specific guild member if they exist.
Due to this system, you cannot deny base permissions. If you grant
@everyone and don't grant it for a muted members role, muted members will still be able to send messages unless you specify channel-based overwrites.
All additional roles allow overwrites are applied after all additional roles denies! If any of a member's roles have an overwrite to allow a permission explicitly, the member can execute the associated actions in this channel regardless of the role hierarchy.
Placing an overwrite to allow
SEND_MESSAGES on a role will result in members with this role not being mutable via role assignment in this channel.
If the guild owner enables the server's two-factor authentication option, everyone executing a specific subset of actions will need to have 2FA enabled on their account. As bots do not have 2FA themselves, you, as the application owner, will need to enable it on your account for your bot to work on those servers. Check out Discord's help articleopen in new window if you need assistance with this.
The permissions assigned to these actions are called "elevated permissions" and are:
Some Discord permissions apply implicitly based on logical use, which can cause unwanted behavior if you are not aware of this fact.
The prime example for implicit permissions is
VIEW_CHANNEL. If this flag is missing in the final permissions, you can't do anything on that channel. It makes sense, right? If you can't view the channel, you can't read or send messages in it, set the topic, or change its name. The library does not handle implicit permissions for you, so understanding how the system works is vital for you as a bot developer.
Let's say you want to send a message to a channel. To prevent unnecessary API calls, you want to make sure your bot's permissions in this channel include
SEND_MESSAGES (more on how to achieve this here). The check passes, but you still can't send the message and are greeted with
DiscordAPIError: Missing Access.
This error means your bot is missing
VIEW_CHANNEL, and as such, can't send messages either.
One possible scenario causing this: the channel has permission overwrites for the default role
@everyone to grant
SEND_MESSAGES so everyone who can see the channel can also write in it, but at the same time has an overwrite to deny
VIEW_CHANNEL to make it only accessible to a subset of members.
As you only check for
SEND_MESSAGES, the bot will try to execute the send, but since
VIEW_CHANNEL is missing, the API denies the request.
Causes for "Missing Access":
- Text Channels require
VIEW_CHANNELas detailed above.
- Voice Channels require
CONNECTin the same way.
- Reacting to a message requires
READ_MESSAGE_HISTORYin the channel the message was sent.
- When deploying slash commands: Enable the
applications.commandsscope (for more information see the adding your bot section).
- Timing out a member requires
Limitations and oddities
- Your bot needs
MANAGE_ROLESin its base permissions to change base permissions.
- It needs
MANAGE_ROLESin its final permissions to change permission overwrites.
- It cannot edit permissions for roles that are higher than or equal to its highest role.
- It cannot grant permissions it doesn't have.
- It can manage overwrites for roles or users with higher roles than its own highest role.
- It can manage overwrites for permissions it doesn't have.
- Members with the
ADMINISTRATORpermission are not affected by overwrites at all.
During your development, you will likely run into
DiscordAPIError: Missing Permissions at some point. One of the following can cause this error:
- Your bot is missing the needed permission to execute this action in its calculated base or final permissions (requirement changes based on the type of action you are trying to perform).
- You provided an invalid permission number while trying to create overwrites. (The calculator on the apps page returns decimal values while the developer documentation lists the flags in hex. Make sure you are not mixing the two and don't use the hex prefix
0xwhere not applicable)
- It is trying to execute an action on a guild member with a role higher than or equal to your bot's highest role.
- It is trying to modify or assign a role higher than or equal to its highest role.
- It is trying to add a managed role to a member.
- It is trying to remove a managed role from a member.
- It is trying to timeout a member with the
- It is trying to execute a forbidden action on the server owner.
- It is trying to execute an action based on another unfulfilled factor (for example, reserved for partnered guilds).
- It is trying to execute an action on a voice channel without the
- It is trying to create a channel or channel overwrite including the
MANAGE_ROLESflag but does not have the
ADMINISTRATORpermission or an explicit
MANAGE_ROLESoverwrite on this channel (note that the global permission does not count)
ADMINISTRATOR permission does not skip any hierarchical check!