Reaction roles

A reaction-role panel is a message members use to give themselves roles. Each role on a panel is offered one way: as a button, as an option in the panel's select menu, or as an emoji reaction. One panel can mix all three. You build panels on the Reaction roles page of the dashboard or with /reactionrole, and both edit the same panels. Epix AI can also create panels, add and remove roles, and post them.

#Setting up a panel

1. 01
   Create the panel

   /reactionrole create name [mode] [title] [description]. The name, up to 100 characters and unique in your server, is how every other subcommand finds the panel; it is matched without regard to case and autocompletes. Title and description become the panel's embed.

2. 02
   Add roles

   /reactionrole addbutton, addoption or addreaction, once per role. Each takes the panel and the role, plus options for how it looks and behaves.

3. 03
   Post it

   /reactionrole send panel [channel] posts it, in the current channel if you name none. Sending a panel that is already posted moves it: the new copy goes up and the old one is deleted.

4. 04
   Edit as you go

   Adding or removing a role on a posted panel updates the live message in place, and new reaction emojis are added to it. There is no need to send it again.

/reactionrole create name:Notifications mode:add
/reactionrole addbutton panel:Notifications role:@Events style:SUCCESS
/reactionrole addoption panel:Notifications role:@Streams description:Stream alerts
/reactionrole send panel:Notifications channel:#roles

/reactionrole removerole panel role takes a role off a panel, /reactionrole list shows every panel in the server, /reactionrole info panel shows one panel's configuration, and /reactionrole delete panel deletes it. Every /reactionrole subcommand needs Manage Roles.

#Three ways to offer a role

An emoji can be a Unicode emoji, a custom emoji, or a theme token such as #[status.success]. A theme token follows your server's theme, so changing the theme changes the emoji on every panel that uses it.

#Modes

The panel's mode is a default, and any role on it can set its own mode instead. That lets one panel offer three opt-in roles and a separate button that only removes. /reactionrole mode panel mode changes the panel's default: roles following the default change with it, and roles with their own mode keep it.

Reactions follow the direction

With reactions, Add / Remove follows the reaction itself: reacting gives the role and removing your reaction takes it away. In Add only and Remove only, removing a reaction never changes anything, and the bot removes the member's reaction after acting so the emoji keeps working as a button. That clean-up needs Manage Messages; without it the panel still works and the count on the emoji simply grows.

The reset option

Discord keeps showing the last option a member picked in a select menu, which makes picking the same role again feel broken. /reactionrole reset panel enabled [label] adds an option ("Reset selection" unless you name it) that clears the menu without touching any roles, so the next pick behaves like a first pick. It only applies to panels that have menu options.

#Panel behaviour

These per-panel settings are on the dashboard, alongside each role's label, emoji, colour, mode and duration.

#Time-limited roles (Premium)

With Premium, any role on a panel can come off on its own. Set a duration between 1 minute and 90 days. In a command, write it like 30m, 2h, 1d12h or 1w; a bare number means minutes, and anything out of range is refused rather than rounded. The dashboard offers presets.

• Expired roles are removed by a check that runs every 15 seconds from stored records, so a role still comes off on time after a bot restart.
• In Add only mode, clicking again while the role is still active renews it and pushes the expiry out. In Add / Remove mode, clicking again takes it off.
• Once a role has expired, the member clicks again to get it back. Nothing renews on its own.
• If the member gives the role back, or it is removed some other way, the timer simply ends.
• If the bot cannot remove an expired role, for example because the role was moved above it, it keeps retrying for up to 7 days.
• If Premium ends, saved durations are kept, but roles are given permanently until Premium returns.

#Which roles can be offered

• The role must be below the bot's highest role, and the bot needs Manage Roles.
• When you add a role with a command, it must also be below your own highest role, so nobody can build a button that hands themselves more than they already have.
• Roles carrying Administrator, Manage Server, Manage Roles or Manage Webhooks can never be self-assigned, and neither can @everyone or a role managed by an integration or Nitro boosting. This is checked again on every click, so a role that gains one of these permissions later stops being handed out.

#Server-wide settings

Run /reactionrole settings with no options to see the current settings and your plan's limits.

#Free and Premium

Panels count whether or not they have been posted, and roles count across buttons, menu options and reactions together.

#What happens when

• A role is deleted from the server: it is removed from every panel, and posted panels update so its button or option disappears.
• The panel's message is deleted: the panel keeps all its settings. Post it again with /reactionrole send.
• You delete a panel: its posted message is deleted too. Members keep the roles they already have, and time-limited roles it gave still expire on schedule.
• A click is refused (the role is too high, the cooldown is running, the panel is off): buttons and menu options answer the member. Reactions cannot be answered, so the bot sends a DM instead, unless the panel is set to reply with nothing.

#Troubleshooting

• "That role is above my highest role": drag the bot's role above it in Server Settings, then try again.
• "That role carries administrative permissions": use a role without Administrator, Manage Server, Manage Roles or Manage Webhooks.
• The count on a reaction keeps growing: in Add / Remove mode this is expected, because each member's reaction is their state. In the other modes, give the bot Manage Messages.
• "This server is at its limit of 3 role panels": delete a panel you no longer use, or upgrade to Premium for 50.