Button Roles

Learn more about Button Roles, a clean and elegant manner for users to gain access to publicly available roles.

SajuukBot will be ceasing operations on March 31st 2024, due to a variety of factors. For more information, please refer to the announcement provided on the SajuukBot discord server and your options for migrating to a new bot.

Buttton Roles are a deprecated feature and is no longer being maintained. Discord released an Onboarding feature in early 2023, which means users have a much cleaner user experience provided by the client for adding and removing self-assignable roles that are defined by the servers' administrators. The feature can also be used to opt-into, or out of, publicly available channels. While SajuukBot will continue to offer Button Roles as an alternative for those communities which are unable to use Onboarding, the feature will receive no further updates, beyond those updates needed to maintain the feature in line with core functionality. If you are able to access Onboarding, please migrate your Button Roles to it: a future update in the bot may begin to restrict access to Button Roles management for those servers above certain member counts. More information on this will be provided in due course.

Being able to manage self-add roles on large communities is usually challenging. Traditional methods that work in much smaller communities, typically with a !role add or !join command in a bot-spam channel, generally fall apart very quickly in larger, more populated communities. There's also the issue of syntax requirements for in-chat bot commands, which can be daunting for users to understand and use properly.

Button Roles is the de facto user experience for managing self-add roles in many communities. Here's why:

• Button Roles don't require the user to use any chat commands to gain/remove roles, they just have to click on buttons from the Bot UI Kit on a defined post to gain roles (or remove them)

• The process is entirely automated in the backend: to the user, they just click buttons that give them roles (or remove them)

• It makes for an easy and non-intimidating welcome page for users to get started.

• Button Roles can also be used as a form of gatekeeping for your community by using it like a role gate, whereby users need to "react" to the given message to confirm they've read the rules, which unlocks your discord server channels.

For a more traditional set up of self-add roles using the bot commands, please navigate to the Self-Add Roles page.

Why Button Roles?

Since 2020, Discord has been working on a new Interactions API whereby bots can utiltise new functionality to improve the user experience of their bots. One of those interaction types is called Buttons, which can serve a huge range of uses, such as for giving/removing roles from a user.

For a long time, bots have traditionally used Reactions as a form of giving and removing roles from users. However, Reactions suffer from some limitations and require a lot of code on the bots' side to process them adequately. For this reason, SajuukBot migrated all Reaction Roles to Button Roles instead. This brought several benefits:

• The backend code needed to power Buttons is significantly simpler than the crazy mess that Reactions required.

• There is no further need for the bot to cache Reactions to reduce querying of the database backend.

• You can have a maximum of 25 buttons on a bot message: this means you can now have 4 extra roles be assigned to buttons instead of the maximum reaction count of 20.

• The user experience is improved because the bot can confirm to the user that they've been given the role, rather than the user guessing that it worked or not (as well as the bot being offline resulting in an error response, so users know if it failed).

So what changed? Surprisingly little will be changing as fundamentally, Button Roles are supposed to feel like an improved Reactions system. However:

• Button Roles can only work on messages generated by the bot. This means a previous ambition to allow roles to be assigned to a regular user message will no longer happen.

• The commands used to generate, add/remove roles or remove a whole message use a very slightly different prefix: !brole instead of !rrole. Functionally all commands perform identically to Reactions, instead they create buttons instead of adding Reactions.

• Internally, the feature continue to be referred to as Reaction Roles, however it is planned to change this in the future once all guilds are migrated to the system.

Configuration

This section of configuration is a root key, which means it should not be indented and in line with the basic settings like levels, prefix and the like. Please see the full basic configuration for more details on how it should be formatted.

reaction roles:
  enabled: false
  description: A list of reaction roles in this server.
  roles:
  channels:
  commands:
    add rr:
      enabled: false
      level: 100
    remove rr:
      enabled: false
      level: 100
    generate:
      enabled: false
      level: 100
    refresh:
      enabled: false
      level: 50
    remove:
      enabled: false
      level: 100

Settings

Each tab contains more details on each setting described in the configuration above.

For more information relating to the commands key, please go to the Commands section below.

The channels setting described below is planned to be removed in a future update. It was only required for Reaction Roles, and is not needed for the DIscord Interactions system at all. Until it is removed, you still need to define it as per the description.

Setting	Description
enabled	Toggles the button roles system on and off. If this is disabled, then the feature is unavailable and commands will not function.
description	A short description that describes the button roles. This should ideally be "generic": this will be used if you do not define one when generating an embed using the !brole generate command in the server.
channels	A list of channel ID's where the bot considers as places for the Button Roles feature to be valid. This is required in order to reduce the amount of backend traffic seen by the bot: it limits the bot to only checking reactions in defined channels rather than "everywhere". If a channel is not defined here, you cannot use !brole generate to make embeds appear in said channel.

Commands

Most of these commands rely on having configured the Button Roles backend properly using the Dashboard page that allows the creation, updating and deletion of the Button Roles that are available. Please refer to the SajuukBot support server if you are unsure on how to configure this.

Due to space constraints, the required syntax of commands, and an example of how they work, are given provided after the list of commands and explanations.

Every command follows the exact same formatting:

• A key called enabled determining if the command is enabled or not.

• A key called level, determining the minimum level required to use the command

At the root of the reaction roles key is an enabled key, which globally controls the commands assigned to this module. If the root key is false, then no command will operate, regardless of whether an individual command is enabled.

All commands are subcommands to the !rrole group.

Command	Description
!brole add_btn	Adds a defined Buttons Role object to an existing embed. The role you add needs to be in the roles configuration setting and the given message to add it to must actually be part of the system.
!brole remove_btn	Removes a defined Button Role object from an existing embed. You can remove any object, even those that are not defined, as long as it hasn't been removed from the backend as being part of the system.
!brole generate	Creates a new Button Role embed with the role objects that have an assigned Message ID of 0 (meaning they are unassigned). You may define a custom description if you do not want to use the default, but the default one must already be configured to use this.
!brole refresh	This command is not available right now.
!brole remove	Removes an existing Button Role embed. This inverts the generate command by assigning any role objects to have a Message ID of 0 before removing the embed from the channel.

Syntax and Examples

Below are the syntax requirements of the above commands, along with an example to show how it works.

Syntax	Examples
!brole add_btn MESSAGE_ID ROLE_ID	!brole add_btn 710909060647747585 767483192638701588
!brole remove_btn MESSAGE_ID ROLE_ID	!brole remove_btn 710909060647747585 767483192638701588
!brole generate CHANNEL	!brole generate #grab-your-roles !brole generate 694614562913124422
!brole remove MESSAGE_ID	!brole remove 710909060647747585