Roles and permissions

A permission lets a member do one thing in a guild, such as send a message or ban another member. Each role grants a set of permissions as a 64-bit mask, and a permission overwrite on a channel changes that set for one channel.

Permissions

Value	Name	Description
1 << 0	CREATE_INSTANT_INVITE	Create an invite to a guild channel
1 << 1	KICK_MEMBERS	Remove a member from the guild
1 << 2	BAN_MEMBERS	Ban and unban members
1 << 3	ADMINISTRATOR	Grants every permission and ignores every channel overwrite
1 << 4	MANAGE_CHANNELS	Create, modify, reorder and delete guild channels
1 << 5	MANAGE_GUILD	Modify guild settings, invites, the vanity URL and discovery
1 << 6	ADD_REACTIONS	Add a reaction to a message
1 << 7	VIEW_AUDIT_LOG	Read the guild audit log
1 << 8	PRIORITY_SPEAKER	Use priority speaker in a voice channel, enforced by the client
1 << 9	STREAM	Share your screen or camera in a voice channel
1 << 10	VIEW_CHANNEL	View a channel
1 << 11	SEND_MESSAGES	Send messages, create forum posts and publish your own announcements
1 << 12	SEND_TTS_MESSAGES	Send a text-to-speech message
1 << 13	MANAGE_MESSAGES	Delete other members' messages and reactions, bulk delete messages and edit other members' message flags and attachments
1 << 14	EMBED_LINKS	Have links in your messages expanded into embeds
1 << 15	ATTACH_FILES	Attach files to a message
1 << 16	READ_MESSAGE_HISTORY	Read messages older than the guild's message_history_cutoff, or any message when the guild has no cutoff
1 << 17	MENTION_EVERYONE	Use the everyone and here mentions
1 << 18	USE_EXTERNAL_EMOJIS	Use emojis from other guilds
1 << 20	CONNECT	Connect to a voice channel
1 << 21	SPEAK	Talk in a voice channel
1 << 22	MUTE_MEMBERS	Mute other members in a voice channel
1 << 23	DEAFEN_MEMBERS	Deafen other members in a voice channel
1 << 24	MOVE_MEMBERS	Move members between voice channels or disconnect them
1 << 25	USE_VAD	Use voice activity detection, enforced by the client
1 << 26	CHANGE_NICKNAME	Change your own nickname
1 << 27	MANAGE_NICKNAMES	Change other members' nicknames
1 << 28	MANAGE_ROLES	Manage roles below your highest role, assign them and set channel overwrites
1 << 29	MANAGE_WEBHOOKS	Create, modify and delete webhooks and follow announcement channels
1 << 30	MANAGE_EXPRESSIONS	Modify and delete emojis and stickers that other members created
1 << 34	MANAGE_THREADS1	Archive, lock, rename and delete threads and see every private thread
1 << 35	CREATE_PUBLIC_THREADS1	Start public and announcement threads
1 << 36	CREATE_PRIVATE_THREADS1	Start private threads
1 << 37	USE_EXTERNAL_STICKERS	Use stickers from other guilds
1 << 38	SEND_MESSAGES_IN_THREADS1	Send messages in threads and add members to them
1 << 40	MODERATE_MEMBERS	Time out members
1 << 43	CREATE_EXPRESSIONS	Create emojis and stickers and edit or delete your own
1 << 51	PIN_MESSAGES	Pin and unpin messages
1 << 52	BYPASS_SLOWMODE	Ignore the channel slowmode
1 << 53	UPDATE_RTC_REGION	Change the voice region of a voice channel
1 << 54	VIEW_CHANNEL_MEMBERS1	View the member list of a channel

¹ The bit is feature-gated. Thread permissions explains how the thread bits apply.

Responses send a permission mask as a decimal string. Requests accept a decimal string up to 9223372036854775807, or a JSON number that is a safe integer. Parse masks as unsigned 64-bit integers. Fluxer drops any bit it doesn't define.

Feature-gated permission bits

You can only write a gated bit when your request declares the feature it needs, in the X-Fluxer-Features header as a comma-separated list.

Bits	Who can write them
VIEW_CHANNEL_MEMBERS	A request that declares view_channel_members_permission
The four thread bits	A bot, or a user session that declares the channel_threads feature

When you can't write a gated bit, Fluxer keeps that bit at its stored value and writes the rest of the mask. A new role created with permissions starts with the bit cleared. One created without permissions copies the everyone role's mask, gated bits included. Callers that can't write the thread bits also don't see them in role masks, overwrite masks or permissions values.

Elevated permissions

KICK_MEMBERS, BAN_MEMBERS, ADMINISTRATOR, MANAGE_CHANNELS, MANAGE_GUILD, MANAGE_MESSAGES, MANAGE_ROLES, MANAGE_WEBHOOKS, MODERATE_MEMBERS and MANAGE_THREADS are elevated. In a guild with the elevated MFA level, a member other than the owner needs two-factor authentication to use them, and gets 400 TWO_FACTOR_REQUIRED without it. Computed permissions values still include these bits.

Permission computation

The guild owner has every permission, and a user who isn't a member has none. For anyone else, Fluxer starts with the everyone role, whose ID is the guild ID, and adds every role the member has. If the result has ADMINISTRATOR, the member has every permission and no overwrite applies.

In a channel, Fluxer then applies the channel's overwrites in this order, removing denied bits before adding allowed bits at each step.

1. The everyone role overwrite.
2. The overwrites for the member's roles, combined, where an allow on one role beats a deny on another.
3. The member's own overwrite.

A category is visible when you can view at least one channel in it. A thread has no overwrites of its own, and Thread permissions explains how its permissions work.

Communication timeout

In a guild channel, a member whose communication_disabled_until is in the future keeps their permissions, but gets 403 COMMUNICATION_DISABLED when they try any of these.

• Send, edit or publish their own message
• Add a reaction or request an attachment upload
• Start typing
• Change their own nickname
• Start, change or delete a thread, or add or remove its members
• Pin or unpin a message in a thread

Check communication_disabled_until as well as the mask before you show these actions.

Role hierarchy

Roles rank by position, and your rank is the rank of your highest role. You can manage a role only when you rank above it, even with MANAGE_ROLES, and the guild owner can manage every role.

A role or overwrite write that grants a permission you don't have fails with MISSING_PERMISSIONS, unless you're the guild owner.

Guild role object

A role is a permission mask that a guild assigns to its members.

Structure

Field	Type	Description
id	snowflake	The ID of the role
name	string	The name of the role (1-100 characters)
color	integer	The color of the role as an RGB integer (0-16777215)
position	integer	The rank of the role, where a larger value ranks higher
hoist_position	?integer	The position of the role's group in the member list, or null to follow position
permissions	decimal string	The permission mask the role grants
hoist	boolean	Whether the role's members show as their own group in the member list
mentionable	boolean	Whether members without MENTION_EVERYONE can mention the role
icon	?string	The hash of the role icon image, or null
unicode_emoji	?string	The Unicode emoji used as the role icon, or null

The everyone role has the guild's ID, is called @everyone and is always at position 0. You can change its color and permissions, but you can't delete it, move it, give it a hoist position or give it an icon.

A role has at most one of icon and unicode_emoji. Clients show the icon of a member's highest role that has one. An image icon is served by the Media Proxy at Get role icon.

Example

{
  "id": "1489002177550843904",
  "name": "Moderator",
  "color": 3447003,
  "position": 4,
  "hoist_position": 1,
  "permissions": "1099511637006",
  "hoist": true,
  "mentionable": false,
  "icon": "5d4c7a1e",
  "unicode_emoji": null
}

Role position object

One entry in a Modify guild role positions request.

Structure

Field	Type	Description
id	snowflake	The ID of the role
position?	integer	The rank you want for the role, where a larger value ranks higher

Role hoist position object

One entry in a Modify role hoist positions request.

Structure

Field	Type	Description
id	snowflake	The ID of the role
hoist_position	integer	The member list position to give the role

List guild roles

GET/v1/guilds/{guild_id}/rolesBotguilds

Returns every guild role object in the guild, highest position first. You need to be a member of the guild, and an OAuth2 token needs the guilds scope.

Response

Status	Body	Condition
200	array[guild role object]	The roles were returned

The rate limit is 60 requests per 10 seconds, on the guild:role:list::guild_id bucket.

Create guild role

POST/v1/guilds/{guild_id}/rolesBotAudit reason

Creates a role at position 1 and returns its guild role object. You need MANAGE_ROLES. Fluxer sends a Guild Role Create event.

Request headers

Field	Type	Description
X-Fluxer-Features?	string	A comma-separated feature declaration

JSON body

Field	Type	Description
name	string	The name of the role (1-100 characters)
color?	integer	The color of the role as an RGB integer (0-16777215, default 0)
permissions?	decimal string | integer	The permission mask, which defaults to the everyone role's mask
icon?	?base64 string	A PNG, JPEG, WebP or AVIF image for the role icon, or null to remove it
unicode_emoji?	?string	A single Unicode emoji for the role icon, or null to remove it
icon_source_role_id?	snowflake	A role in this guild whose icon the new role copies

With icon_source_role_id, Fluxer stores a separate copy of an image icon. Deleting either role leaves the other's icon in place.

Response

Status	Body	Condition
200	guild role object	The role was created
400	error response	MAX_GUILD_ROLES when the guild is at its role limit, 250 by default, counting the everyone role
400	error response	A role icon is not valid
400	error response	ROLE_ICON_SOURCE_AND_ICON_EXCLUSIVE when icon_source_role_id comes with icon or unicode_emoji
404	error response	UNKNOWN_ROLE when icon_source_role_id is not a role in this guild
413	error response	The body is larger than a role icon allows

The rate limit is 10 requests per minute, on the guild:role:create::guild_id bucket.

Modify guild role

PATCH/v1/guilds/{guild_id}/roles/{role_id}BotAudit reason

Modifies a role and returns its guild role object. You need MANAGE_ROLES and must outrank the role. Fluxer sends a Guild Role Update event.

Request headers

Field	Type	Description
X-Fluxer-Features?	string	A comma-separated feature declaration

JSON body

Fields you leave out keep their value. On the everyone role, Fluxer ignores every field except color, permissions, icon and unicode_emoji, and the last two can only be null.

Field	Type	Description
name?	string	The name of the role (1-100 characters)
color?	integer	The color of the role as an RGB integer (0-16777215)
permissions?	decimal string | integer	The new permission mask, which replaces the old one
hoist?	boolean	Whether the role's members show as their own group in the member list
hoist_position?	?integer	The member list position to give the role, or null to clear it
mentionable?	boolean	Whether members without MENTION_EVERYONE can mention the role
icon?	?base64 string	A PNG, JPEG, WebP or AVIF image for the role icon, or null to remove it
unicode_emoji?	?string	A single Unicode emoji for the role icon, or null to remove it

Response

Status	Body	Condition
200	guild role object	The role was modified
400	error response	A role icon is not valid
413	error response	The body is larger than a role icon allows

The rate limit is 20 requests per 10 seconds, on the guild:role:update::guild_id bucket.

Role icons

Create guild role and Modify guild role take the same two icon fields.

Body	Result
field left out	The icon stays as it is
icon with an image	The image is stored and unicode_emoji is cleared
unicode_emoji with an emoji	The emoji is stored and any image is cleared
icon set to null	The image is cleared
unicode_emoji set to null	The emoji is cleared
both non-null	400 with ROLE_ICON_AND_EMOJI_EXCLUSIVE on icon
either non-null on the everyone role	400 with CANNOT_SET_ICON_ON_EVERYONE_ROLE on that field

An image can't be animated, can be at most 256 KiB and each side must be between 32 and 1024 pixels. An image outside these limits returns 400 with IMAGE_SIZE_EXCEEDS_LIMIT, INVALID_IMAGE_FORMAT or IMAGE_DIMENSIONS_OUT_OF_RANGE, and an emoji that isn't a single Unicode emoji returns NOT_A_VALID_UNICODE_EMOJI. Role icons are free and need no guild feature. When an image is replaced or cleared, or the role is deleted, Fluxer deletes the old image later.

Modify guild role positions

PATCH/v1/guilds/{guild_id}/rolesBotAudit reason

Reorders roles and returns 204. You need MANAGE_ROLES and must outrank every role whose position you change. Fluxer sends a Guild Role Update Bulk event with the stored positions.

Fluxer sorts the roles you can manage by the positions you send and keeps roles you can't manage at their rank. It then renumbers every role except the everyone role from 1, so the stored position can differ from the one you sent.

JSON body

An array of role position objects. The everyone role can't be in it.

Response

Status	Body	Condition
204	empty	The positions were applied
400	error response	An entry is the everyone role or a role that doesn't exist
423	error response	Another position change is still running

The rate limit is 20 requests per 10 seconds, on the guild:role:positions::guild_id bucket.

Modify role hoist positions

PATCH/v1/guilds/{guild_id}/roles/hoist-positionsBotAudit reason

Sets the member list position of one or more roles and returns 204. You need MANAGE_ROLES and must outrank every role you name. Fluxer sends a Guild Role Update Bulk event.

JSON body

An array of role hoist position objects. The everyone role can't be in it.

Response

Status	Body	Condition
204	empty	The hoist positions were applied
400	error response	An entry is the everyone role or a role that doesn't exist
423	error response	Another hoist position change is still running

The rate limit is 20 requests per 10 seconds, on the guild:role:hoist_positions::guild_id bucket.

Reset role hoist positions

DELETE/v1/guilds/{guild_id}/roles/hoist-positionsBotAudit reason

Clears the member list position of every role in the guild, including roles you don't outrank, and returns 204. You need MANAGE_ROLES. Fluxer sends a Guild Role Update Bulk event.

Response

Status	Body	Condition
204	empty	The hoist positions were cleared
423	error response	Another hoist position change is still running

The rate limit is 10 requests per minute, on the guild:role:hoist_positions_reset::guild_id bucket.

Delete guild role

DELETE/v1/guilds/{guild_id}/roles/{role_id}BotAudit reason

Deletes a role, removes it from every member who has it and returns 204. You need MANAGE_ROLES and must outrank the role. You can't delete the everyone role. Fluxer sends a Guild Role Delete event.

Response

Status	Body	Condition
204	empty	The role was deleted

The rate limit is 10 requests per minute, on the guild:role:delete::guild_id bucket.