Reaction Roles
Information about Ser Aymeric's reaction roles system.
What are Reaction Roles?
Reaction Roles is the name of a feature that Ser Aymeric provides where you can link roles in your Discord server with specific default or custom Discord emoji. Ser Aymeric can post a message to a channel within your Discord server which users can react to with an emoji to obtain the role that you've linked to it. It's a useful and fun way to allow your users to manage their own roles for channel access and nickname colours, for example.
The great thing about Ser Aymeric is that you can do so much more with reaction roles than simply allow users to manage their own roles role. You can also configure role requirements, additional actions and impose other limitations. It can be a tool to reward your members and encourage them to participate in your community.
Permissions
Please ensure that Ser Aymeric's role has permissions to Read Messages, Send Messages, Add Reactions, Manage Messages in the channel the reaction role messages will be posted to. Manage Roles is also required and Ser Aymeric's own role in your Discord's role hierarchy must be above any (in a literal sense) that you have configured to allow him to assign to other users.
Some owners use channel overrides to restrict access to Discord bots to certain channels, which is perfectly fine, even encouraged! However, if you've added channel overrides for Ser Aymeric, please ensure they do not counter any of these permissions you've added on his main role as channel overrides take precedence. Please see Discord's permissions guide for more information.
Where to configure?
Please log in to Ser Aymeric's website and select the settings option from the drop down menu that appears when you hover over your Discord's icon in the navigation bar. Then, from the grid of module buttons, select Reaction Roles.
Module buttons may be dimmed or disabled if the module is either turned off, or you don't have access to the feature because it's a reward for subscribing to Ser Aymeric's premium services.
Only the owner of a Discord and members with a role with the administrator checkbox enabled can access your Discord's settings page, unless you have configured additional bot administrators in the general settings tab.
Example
Your goal for fully functional reaction roles is to make your community's reaction roles management page look something like the following screenshot.
There's a lot happening in this screenshot and we'll talk you through all of it. Essentially, it shows a list of reaction role messages you've set up for your community and any reactions you've added to the message that your members can select to obtain roles. This configuration, for example, when posted to a channel in your Discord server will look like the following screenshot.
You can see that there are two embed messages. The first has a title "Name Colours" and a custom description text which includes some Discord compatible markdown. There is also a list of emojis, with the corresponding role that will be obtained and some extra optional information about the reaction roles such as whether or not there are any requirements that members must meet before they can obtain an individual role. Finally, the message has a number of reactions placed onto the message already. These have been added by Ser Aymeric so that your members don't have to search for the correct emoji to react to themselves - they only need to click the relevent one! The second message is more simple, it has a tile "News & Announcements" with a custom description, a custom embed colour (yellow in this case) and a simple list of custom and default emojis.
Before we discuss how to configure reaction roles in detail, let's first see an overview of all the possible options and settings you can use to customise Ser Aymeric's reaction role system for your users.
Overview
Here's a list of core features at a glance.
When one of your members adds a reaction, Ser Aymeric will leave it there by default. This means that to toggle a role off again, the member simply needs to remove their own reaction from the message. However, you can set Ser Aymeric to automatically remove member reactions. In this case, a user will have to react to a message a second time to remove the role.
You can configure reaction roles to not be removable (once they have picked a role, they can't remove it again).
You can use both custom and default emoji with Ser Aymeric's reaction roles system. Custom emoji will be available to select from the list of your own community's list of custom emoji. This means that if you'd like to use a specific emoji, you simply need to upload it within your own community.
You can allow your members to select multiple roles from a specific message, or to have only one role from the message at a time. If you use the latter option, other roles in the message will be removed when the member adds another reaction to the same message.
You can implement role requirements. In some cases, you may want to prevent members from obtaining certain roles unless they have met certain requirements. For example, if they've been a member of your community for x amount of days, or if they have already obtained another role. This is a way for you to offer "rewards" to your members, for activity or something else. A great integration for role requirements is Ser Aymeric's profiles module, where you can assign a role to members as a reward for reaching a certain level within your community. Level increases are awarded by experience points gains when members interact within your community.
You can use markdown in your reaction role message description.
You can re-order your emojis by dragging and dropping them.
Reaction Modes
For some reaction roles, you may be happy to leave the user's reaction on a reaction roles message. In this case, the user will simply need to remove their reaction to toggle the respective role off (if you have permitted role removal).
In other cases, users may prefer to not have their reaction left on the message as the reaction list for messages within Discord are publicly accessible. You can instruct Ser Aymeric to automatically remove a reaction again after the user has reacted. In this reaction mode, the user will need to react again to the message to remove the role.
User Feedback
When your members have reacted to one of your reaction role messages, they will be expecting a change to their roles. However, it may still be appropriate to let Ser Aymeric attempt to send them a DM confirming the success or failure of the role change - it's good user feedback.
Some users may find DMs annoying though, so we've left it to you to decide what's best for your own community in this case.
DMs will not be sent successfully if the user has disabled them.
These are the messages that will be sent to your members when they interact with your reaction roles in different scenarios. Red indicates failed requests due to permissions errors, orange are denied request due to role requirements not having been met by the requester, for example and no colour means a successful role change has occured.
Configure Messages
To create a reaction role message, please click the + button in the bar that reads Reaction Role Messages.
This bar also contains information about how many messages you have added, and the total you can add. Please not that this only refers to the amount of messages you've configured. It does not count how many you've posted to a channel in your Discord.
A popup will appear that will allow you to customise your reaction roles message. This will change the look of the Discord embed message that you will later post to a channel and leave in place for your members to react to.
Description allows for up to 300 characters. Discord embed descriptions allow for up to 2048 characters and you will need most of these to list the reaction roles you've configured. Enabling role requirements and role actions will take up additional characters.
Allow 1 role per message
You can set the message to only allow your members to select one role at a time from the menu. This means that when they react to the message that other roles in this message will be removed.
Don't enable this if you'd like your members to be able to obtain multiple roles from the menu.
Colour Picker
You can pick whichever colour you'd like, simply click on the colour input text box with the hexadecimal colour code to open the colour picker.
The button to the right called "Use Default" will revert your setting back to default.
Please do make sure that the value you enter is a valid hexadecimal colour code.
Markdown
The description field will allow you to use Discord's markdown. Please see Discord's own guide on markdown a link to which is in the useful information section on the left navigation bar of this documentation. Markdown allows you to further customise your text and can help you to highlight key information about your reaction roles. Click the Save button when you're done! Don't worry, you can edit your configuration later.
Overview
You have now added your first reaction role message configuration. This message has not yet been posted to a channel in your Discord, so the left border will be red and the buttons to update and delete your message within Discord will be disabled.
Here you can see the title of your reaction roles message and how many characters of the 2048 allowance have been used up. This will update automatically as you add and remove reaction roles. The buttons on the right will allow you to add a reaction role to the message (+), edit the message (cog) or remove it from your configuration (-).
The buttons on the left allow you to manage the actual reaction roles message within your Discord.
Please take note of the character count. This will update automatically as you change your configuration but must not exceed 2048 characters.
Let's add some reactions. Click on the + button.
Configure Reactions
Now that you have configured a reaction role message, you will need to configure some roles and specify which emoji your members can react to the message with to obtain it.
Click the + button on a reaction roles message to add a reaction and instruct Ser Aymeric what to do when one of your members reacts to the message. This will open a popup.
Here you will be required to select either a custom or default emoji to add to the message and a role to toggle on the user when they react, all other options in the popup are optional.
Emoji Picker
Custom emojis (the first tab with a Discord icon) are taken directly from your own Discord server. You can simply upload more custom emoji if you'd like additional options, but please be aware that it may take Ser Aymeric a few minutes to update its cache. You can also add default emoji that is compatible with Discord.
You can search emoji using their Discord names. For example, if you type in :smiley_cat: in Discord you can use the search terms: smiley, smiley cat, or smiley_cat. This field is not case sensitive.
Irremovable roles
You can set roles as irremovable. This means that when a user has reacted to a message to pick up a role, removing their reaction or reacting again (depending on which reaction mode you have selected) will not allow them to remove the role themselves.
Role Requirements
Some times you may want to allow your users to obtain roles on certain conditions. Perhaps you'd like to reward your members for sticking around for a couple of weeks, or even have them reach a certain level with Ser Aymeric's profiles & levelling module through being active in your community.
Role requirements allow you to do this with reaction roles, and makes it possible for you to time-gate or activity-gate certain features within your Discord such as nickname colours or channel access, etc.
See our documentation on Ser Aymeric's profiles and levelling features for more information on how to integrate reaction roles with the level-up system and role rewards.
Role Actions
I've not written this section yet as I still have decisions to make on the implementation.
Please stay tuned for more!
Reordering Reactions
You may also reorder your reactions after you've added them by simply dragging and dropping the element that contains reaction configuration.
Reordering reactions on the website will not reorder the reactions on the message in Discord after you've added it automatically. You will need to delete the message and repost it if you'd like the order to be changed after you've posted.
Saving Configuration
The website will tell you when you have made changes to your reaction roles and will give you the option to save your changes so that they will not be lost if you leave the page. Please note however, that posting or importing your reaction role message will cause your configuration to be saved automatically. This is to ensure that the messages you have in Discord work right away, regardless of whether or not you forget to manually save.
Managing Messages
Now that you've configured some messages and emoji for your members to react to, it's time to get the message posted in to your Discord so they can use them!
Your configuration will look something like what's shown in the following image.
A red left border and disabled update and delete buttons means that the message configuration has not yet been posted into your Discord.
A blurple left border and enabled update and delete buttons means that the message configuration has been posted into your Discord and can now be used.
Posting
Clicking on the post button will send your reaction roles configuration to a channel in your Discord server. It can take some time for this task to finish due to Discord's API rate limits, especially if you have a lot of reactions so please be patient.
If you already have posted a reaction role message to a channel within your Discord and you click post again, the previous message will be deleted and your message will be posted anew.
Your reaction roles will be immediately ready for use!
Updating
Clicking on the update button will simply cause your reaction role message within your Discord server to be updated. Any reactions you've removed or added on the website will also be removed or added on the message in Discord.
Deleting
Clicking on the delete button will simply remove the message from within your Discord, but will not delete the configuration itself. This allows you to remove the message without losing your configuration should you want to use it again at later date.
Importing
The import function was created to make it easy to convert from the old reaction roles system to the new one. In the old system you created reaction roles and used the ?rroles command in Discord. Ser Aymeric did not store the Message ID when this command was used. However, the new system does, and made it possible to add an array of new features and optimisations for how people actually use reaction role systems, which is to simply put the message in a channel and leave it there.
The purpose of the import function is to update your reaction roles messages to the new system without having to post a new message. This is for those of you that want to keep the reactions that your existing messages on them. If you don't care about your reactions, you can simply post a new message to use the new system.
To import your old reaction role message to the new system, simply get the Message ID from your existing reaction role message in a channel in your Discord. You might need to enable developer mode in Discord's user settings first.
Once you have the message ID, you can then click on the import button in the relevant message on the website. Select the channel that the existing reaction roles message is in and enter the message ID that you have just copied.
When importing, Ser Aymeric will simply update the message content, and add and remove any reactions that you've added or removed from the message settings on the website (if you have added or removed any, that is). Afterwards, the message ID will be saved so that you can make further changes to the message from the website without having to use confusing commands within Discord!
Audit Logging
When making changes to a user's roles, Ser Aymeric will explain why in your Discord's audit logs. This is partly so you know exactly what Ser Aymeric is doing, but will also help you support your members with the feature.
Troubleshooting
Here are some tips to help you figure out any problems with your reaction role settings or permissions within Discord that may be preventing reaction roles working. However, if you find yourself struggling to get things working, please come and talk to the Developers in our Discord, we will be happy to help!
Reaction Roles is a feature accessible by communities that have Ser Aymeric Premium.
Please ensure that Ser Aymeric's role has permissions to Read Messages, Send Messages, Add Reactions, Manage Messages in the channel the reaction role messages will be posted to. Manage Roles and Ser Aymeric's own role in your Discord's role hierarchy must be above (in a literal sense) any that you have configured to allow him to assign to other users.
Your message may contain up to 2048 characters, which includes the list of emoji and the corresponding role they give and any information about requirements members must meet before they can obtain a role. You can use Discord markdown here too.
If you make any changes to your reaction roles message, or the reaction roles themselves, don't forget to click the update button to update the message within Discord if you've posted one.
When making changes to your Discord such as adding new custom emoji or changing the positions of roles in your role hierarchy, it may take a short time for those changes to update on Ser Aymeric's website due to temporary caching.
Reordering reactions on the website will not reorder the reactions on the message in Discord after you've posted it automatically. You will need to delete the message and repost it if you'd like the order to be changed after you've posted.
Last updated
