Skip to main content

​
Role

Represents a Discord role in a guild.

​
Attributes

​
id
int
The ID for the role.
​
name
str
The name of the role.
​
guild
Guild
The guild the role belongs to.
​
position
int
The position of the role. This number is usually positive. The bottom role has a position of 0.
Multiple roles can have the same position number. As a consequence of this, comparing via role position is prone to subtle bugs if checking for role hierarchy. The recommended and correct way to compare for roles in the hierarchy is using the comparison operators on the role objects themselves.
​
permissions
Permissions
Returns the role’s permissions.
​
colours
RoleColours
The role’s colours. Aliased to colors.
​
hoist
bool
Indicates if the role will be displayed separately from other members.
​
managed
bool
Indicates if the role is managed by the guild. This is true if any of Role.is_integration(), Role.is_premium_subscriber(), Role.is_bot_managed() or Role.is_guild_connections_role() is True.
​
mentionable
bool
Indicates if the role can be mentioned by users.
​
tags
RoleTags | None
The role tags associated with this role.
​
icon
Asset | None
Returns the role’s icon asset, if available.
​
unicode_emoji
str | None
The role’s unicode emoji. Only available to guilds that contain ROLE_ICONS in Guild.features.
​
created_at
datetime
Returns the role’s creation time in UTC.
​
mention
str
Returns a string that allows you to mention a role.
​
members
list[Member]
Returns all the members with this role.

​
Methods

Checks if the role is the default role (@everyone).Returns: bool - True if this is the @everyone role.Example:
if role.is_default():
    print("This is the @everyone role")
Whether the role is associated with a bot.Returns: bool - True if the role is managed by a bot.Example:
if role.is_bot_managed():
    print("This role is managed by a bot")
Whether the role is the premium subscriber, AKA “boost”, role for the guild.Returns: bool - True if this is the server boost role.Example:
if role.is_premium_subscriber():
    print("This is the boost role")
Whether the guild manages the role through some form of integrations such as Twitch or through guild subscriptions.Returns: bool - True if the role is an integration role.
Whether the role is able to be assigned or removed by the bot. This checks whether all of the following conditions are true:
  • The role is not the guild’s default role
  • The role is not managed
  • The bot has the manage_roles permission
  • The bot’s top role is above this role
Returns: bool - True if the role can be assigned.Example:
if role.is_assignable():
    await member.add_roles(role)
Edits the role.
You must have the manage_roles permission to use this.
​
name
str
The new role name to change to.
​
permissions
Permissions
The new permissions to change to.
​
colours
RoleColours
The new colours to change to.
​
hoist
bool
Indicates if the role should be shown separately in the member list.
​
mentionable
bool
Indicates if the role should be mentionable by others.
​
position
int
The new role’s position. This must be below your top role’s position, or it will fail.
​
icon
bytes | None
A bytes-like object representing the icon. Only PNG/JPEG/WebP is supported. Could be None to denote removal of the icon.
​
unicode_emoji
str | None
The role’s unicode emoji.
​
reason
str
The reason for editing this role. Shows up on the audit log.
Returns: Role - The newly edited role.Example:
await role.edit(name="New Name", colour=discord.Colour.red())
Deletes the role.
You must have the manage_roles permission to use this.
​
reason
str
The reason for deleting this role. Shows up on the audit log.
Example:
await role.delete(reason="No longer needed")

​
RoleTags

Represents tags on a role. A role tag is a piece of extra information attached to a managed role that gives it context for the reason the role is managed.

​
Attributes

​
bot_id
int | None
The bot’s user ID that manages this role.
​
integration_id
int | None
The integration ID that manages the role.
​
subscription_listing_id
int | None
The subscription SKU and listing ID of the role.

​
Methods

Whether the role is associated with a bot.Returns: bool
Whether the role is the premium subscriber, AKA “boost”, role for the guild.Returns: bool
Whether the guild manages the role through some form of integrations such as Twitch or through guild subscriptions.Returns: bool
Whether the role is available for purchase.Returns: bool - True if the role is available for purchase, and False if it is not available for purchase or if the role is not linked to a guild subscription.
Whether the role is a guild connections role.Returns: bool

​
RoleColours

Represents a role’s gradient colours.

​
Attributes

​
primary
Colour
The primary colour of the role.
​
secondary
Colour | None
The secondary colour of the role.
​
tertiary
Colour | None
The tertiary colour of the role. At the moment, only 16761760 is allowed.
​
is_holographic
bool
Whether the role is holographic. Currently roles are holographic when colours are set to 11127295, 16759788, and 16761760.

​
Class Methods

Returns a default RoleColours object with no colours set.Returns: RoleColoursExample:
colours = discord.RoleColours.default()
Returns a RoleColours that makes the role look holographic.
Currently holographic roles are only supported with colours 11127295, 16759788, and 16761760.
Returns: RoleColoursExample:
colours = discord.RoleColours.holographic()
await role.edit(colours=colours)

Build docs developers (and LLMs) love

Get started for freeTalk to us