Skip to main content
Represents a Guild’s Role. Used to control permissions for Members.

​
Overview

Roles are used to organize members and assign permissions in a guild. Each role has a position, color, and set of permissions.

​
Key Properties

​
Basic Information

​
getId()
String
The Snowflake id of this Role.
String roleId = role.getId();
​
getIdLong()
long
The Snowflake id of this Role as a primitive long.
long roleId = role.getIdLong();
​
getName()
String
The name of this Role.
String name = role.getName();
​
getGuild()
Guild
Returns the Guild this Role exists in.
Guild guild = role.getGuild();

​
Position and Hierarchy

​
getPosition()
int
The hierarchical position of this Role in the Guild hierarchy (higher value means higher role).The @everyone role always returns -1.
int position = role.getPosition();
​
getPositionRaw()
int
The actual position of the Role as stored by Discord.
int rawPosition = role.getPositionRaw();
​
canInteract(Role role)
boolean
Whether this Role can interact with the specified Role (move/manage/etc.).
if (moderatorRole.canInteract(memberRole)) {
    // Can manage this role
}

​
Permissions

​
getPermissions()
EnumSet<Permission>
Gets the Permissions that this Role has.
EnumSet<Permission> permissions = role.getPermissions();
if (permissions.contains(Permission.ADMINISTRATOR)) {
    System.out.println("Admin role");
}
​
getPermissionsRaw()
long
The long representation of the literal permissions that this Role has.
long permissions = role.getPermissionsRaw();
​
hasPermission(Permission... permissions)
boolean
Checks whether this role has the specified permissions.
if (role.hasPermission(Permission.KICK_MEMBERS)) {
    System.out.println("Can kick members");
}

​
Appearance

​
getColors()
RoleColors
The colors this Role is displayed in.
RoleColors colors = role.getColors();
Color primary = colors.getPrimary();
​
getColor()
Color
The color this Role is displayed in.Returns null if the role uses the default color.
Color color = role.getColor();
if (color != null) {
    System.out.println("RGB: " + color.getRGB());
}
​
getColorRaw()
int
The raw color RGB value used for this role.Defaults to Role.DEFAULT_COLOR_RAW if this role has no set color.
int colorRaw = role.getColorRaw();
​
getIcon()
RoleIcon
The Icon of this role.Returns null if no custom image or emoji is set.
RoleIcon icon = role.getIcon();
if (icon != null) {
    String iconUrl = icon.getIconUrl();
}

​
Display Settings

​
isHoisted()
boolean
Whether this Role is hoisted. Members in a hoisted role are displayed in their own grouping on the user-list.
if (role.isHoisted()) {
    System.out.println("Displayed separately");
}
​
isMentionable()
boolean
Whether this role is mentionable.
if (role.isMentionable()) {
    channel.sendMessage(role.getAsMention()).queue();
}
​
getAsMention()
String
Returns a mention tag for this role.
String mention = role.getAsMention(); // Returns: <@&roleId>

​
Special Roles

​
isPublicRole()
boolean
Whether this role is the @everyone role for its Guild, which is assigned to everyone who joins the Guild.
if (role.isPublicRole()) {
    System.out.println("This is the @everyone role");
}
​
isManaged()
boolean
Whether this Role is managed by an integration.
if (role.isManaged()) {
    System.out.println("Cannot be manually assigned");
}
​
getTags()
RoleTags
The tags of this role. Useful to determine the purpose of a managed role.Requires the ROLE_TAGS cache flag to be enabled.
RoleTags tags = role.getTags();
if (tags.isBot()) {
    long botId = tags.getBotIdLong();
}
if (tags.isBoost()) {
    System.out.println("Server boost role");
}

​
Role Actions

​
Management

​
getManager()
RoleManager
The RoleManager for this Role. Used to modify role settings.
role.getManager()
    .setName("Updated Name")
    .setColor(Color.BLUE)
    .setPermissions(Permission.MESSAGE_SEND)
    .queue();
​
delete()
AuditableRestAction<Void>
Deletes this Role.
role.delete()
    .reason("No longer needed")
    .queue();

​
Creating Roles

​
createCopy()
RoleAction
Creates a new Role in this Guild with the same settings as this role.It will be placed at the bottom to avoid permission hierarchy conflicts.
role.createCopy()
    .setName("Copy of " + role.getName())
    .queue();
​
createCopy(Guild guild)
RoleAction
Creates a new Role in the specified Guild with the same settings as this role.
role.createCopy(targetGuild)
    .queue();

​
Role Tags

The RoleTags interface provides information about managed roles:
​
isBot()
boolean
Whether this role is associated with a bot.
​
getBotIdLong()
long
The id for the bot associated with this role.Returns 0 if this role is not for a bot.
​
isBoost()
boolean
Whether this role is the boost role of this guild.
​
isIntegration()
boolean
Whether this role is managed by an integration.This is usually true for roles such as those created for Twitch subscribers.
​
getIntegrationIdLong()
long
The id for the integration associated with this role.Returns 0 if this role is not for an integration.
​
hasSubscriptionListing()
boolean
Whether this role can be acquired through a premium subscription purchase.
​
isAvailableForPurchase()
boolean
Whether this role has been published for user purchasing.
​
isLinkedRole()
boolean
Whether this role is acquired through a user connection.

​
Usage Example

// Get role information
Role role = guild.getRoleById(roleId);
System.out.println("Role: " + role.getName());
System.out.println("Position: " + role.getPosition());
System.out.println("Color: " + role.getColor());

// Check permissions
if (role.hasPermission(Permission.ADMINISTRATOR)) {
    System.out.println("This role has admin permissions");
}

// Modify role
role.getManager()
    .setName("Updated Role")
    .setColor(Color.BLUE)
    .setHoisted(true)
    .setMentionable(true)
    .queue();

// Create new role
guild.createRole()
    .setName("Moderator")
    .setColor(Color.GREEN)
    .setPermissions(
        Permission.KICK_MEMBERS,
        Permission.BAN_MEMBERS,
        Permission.MESSAGE_MANAGE
    )
    .queue(newRole -> {
        System.out.println("Created role: " + newRole.getName());
    });

// Assign role to member
guild.addRoleToMember(member, role)
    .queue();

// Remove role from member
guild.removeRoleFromMember(member, role)
    .queue();

// Check role tags
RoleTags tags = role.getTags();
if (tags.isBot()) {
    System.out.println("This is a bot role");
}
if (tags.isBoost()) {
    System.out.println("This is the server boost role");
}

// Compare roles
if (moderatorRole.canInteract(memberRole)) {
    System.out.println("Moderator role is higher than member role");
}

​
Constants

​
DEFAULT_COLOR_RAW
int
Used to keep consistency between color values: 0x1F_FFFFFF

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us