Set up a Discord reaction roles bot

Before you start

• A bot that is online in your server, with Pro.
• Discord only lets a bot with Manage Roles give out roles ranked below its own top role, so place the bot’s role high in the list. In the panel channel, the bot also has to send messages, embed links, add reactions and read message history.
• Manage Roles on your own account, which every Reaction Roles command requires, and a second account with no staff roles for testing.

1. Set the defaults in the dashboard

   Switch on Reaction Roles in your bot’s Modules tab, open its gear button titled Settings and choose your server. Enable Reaction Roles starts switched on. While it is off, the bot ignores reactions on every panel and refuses to open the wizard. Default Panel Channel is optional: pick a text channel the bot can post in and the wizard skips its channel step, or leave None so it asks every time.

   Default Panel Title starts as “React to get your roles!” and Default Panel Description as “Click on the reactions below to assign yourself roles.” Panel Embed Color defaults to #5865F2. Max Roles Per Panel accepts 1 to 20 and defaults to 20; the wizard and rradd stop adding emoji-role pairs to a panel at that number. Click Save Settings and wait for Saved ✓.

2. Decide what removing a reaction does

   Allow Role Removal On Reaction Remove is on by default, so taking a reaction off a panel also takes away its role. Turn it off when roles should stay once granted. The panel footer tells members which rule applies, but that footer is written when the panel is posted or updated, so older panels keep the old wording after you change the setting.

   DM On Role Change, also on by default, sends the member a direct message naming the role they received. It is sent only when a role is added, never on removal, and a member with closed DMs still gets the role. A member who already holds the role gets nothing new when they react.

3. Build a panel with the wizard

   In any channel, run reactionrole, or its short form rr. Pick the panel’s channel from the menu, which lists up to 25 text channels the bot can post in. Then choose Customize Title & Description to change the title, description and color for this panel only, or Use Defaults & Add Roles to keep your dashboard text. The wizard belongs to whoever started it, and a Cancel button stops it at any step.

   Next, choose a role, then its emoji from a menu of 24 common emoji or type your own with Custom Emoji, and repeat for each role. The role menu offers only roles below the bot’s highest role, leaves out @everyone and roles managed by integrations, and shows at most the 25 highest. Each emoji can be used once per panel. Preview shows the panel only to you, and Finish & Create posts it, adds every emoji as a reaction and replies with the panel’s message ID.

   Example — create a safe interests panel: start rr in #roles, keep the defaults, map 🎮 to @Gaming and 🔔 to @Event Pings, then select Preview and Finish & Create. From an ordinary member account, react with 🎮 and confirm that only @Gaming appears. Remove 🎮 and confirm the role is removed when Allow Role Removal On Reaction Remove is on.

4. Attach roles to an existing message with rradd

   rradd adds a reaction role to a message that already exists, such as your rules post. It takes the channel, the message ID, the emoji and the role, for example rradd #roles 123456789012345678 🎮 @Gaming. The bot reacts to that message with the emoji and saves the pair; repeating it with the same emoji points that emoji at a different role. Unlike the wizard, rradd does not check the role order, so test each role you add this way.

5. List, change and delete panels

   The listroles command, alias rrlist, shows up to ten panels in the server with their channel, message ID and emoji-role pairs. If you pick a channel that already has panels, the wizard lists them; choose one, change its roles, then click Update Panel. It edits that same message in place, keeps its channel and message ID, updates the embed and adds or removes only the changed emoji reactions, so the existing emoji-role mappings keep working. If someone deleted the original message, Update Panel posts a replacement and saves its new message ID instead.

   deleterole takes the panel’s message ID; rrdelete does the same. It stops the bot from watching that message and deletes the message. That includes a post you attached roles to with rradd, if the bot has Manage Messages there, so copy its text first. Roles that members already received stay. rrsettings on its own shows the saved defaults, followed by enabled, channel, title, description, color, maxroles, allowremove or dm and a value it changes the same values as the dashboard, and reset restores the defaults.

6. Test from an ordinary account

   With your second account, react to the panel. The role should appear on that account within a moment, along with a direct message if DM On Role Change is on. Remove the reaction and, with role removal on, the role should go again. Reactions from bot accounts are ignored, so a test from another bot proves nothing.

   If a reaction does nothing, first check that Enable Reaction Roles is on. Next, open Server Settings › Roles in Discord: the bot’s highest role must be above the role, and the bot needs Manage Roles. Moving the bot’s role takes effect at once without rebuilding the panel. Emoji must match exactly, and the bot never matches animated custom emoji, so pick a standard emoji or a still emoji from your own server.

7. Plans and what happens on Free

   Reaction Roles belongs to Pro and is missing from the Free plan. If you move from Pro to Free, the module is switched off on your bots and reactions stop granting or removing roles. Members keep the roles they already have, the saved settings are kept, and upgrading to Pro switches Reaction Roles back on.