Reaction Roles
Allow users to self-assign roles by reacting to messages with emojis.
Overview
Reaction roles let users gain access to roles, channels, and features by simply reacting to a message with an emoji. This is a self-service system that reduces moderation work and gives users agency over their own experience.
When a user reacts with the configured emoji, the bot automatically assigns the corresponding role. Removing the reaction removes the role. This makes it easy for users to join communities, opt-in to notifications, or access category-specific channels.
Common Use Cases
Reaction roles are perfect for these scenarios:
Gaming Roles
Users react to get roles for different game communities (Minecraft, Valorant, etc)
Notification Opt-ins
Subscribe to announcement channels, event notifications, or update alerts
Language/Region Selection
Users select their preferred language or region for localized content
Interest Groups
Join communities based on interests: Art, Music, Tech, Sports, etc
Skill Levels
Self-identify your experience level: Beginner, Intermediate, Advanced, Expert
Team Selection
Join teams, departments, or groups within the organization
Platform Selection
Indicate which platforms you use: PC, Console, Mobile, etc
Pronoun/Identity Roles
Set preferred pronouns, genders, or identity roles for inclusivity
Setting Up Reaction Roles
Follow these steps to create a reaction role system:
Create the Message
Use a custom command or send a message manually describing what roles are available. This message will receive reactions.
Identify Message ID
Copy the message ID by hovering over the message and selecting "Copy Message ID" (enable Developer Mode in Discord settings).
Configure Emoji-Role Mappings
Set up which emoji corresponds to which role. One emoji = one role.
Enable Reaction Listener
Activate the reaction role system with the configured message and mappings.
Test the System
React to the message with the configured emoji and verify the role is assigned.
Reaction Role Commands
Manage reaction role systems with these commands:
/reactionrole setup | Start the interactive reaction role setup |
/reactionrole create <msg_id> | Create reaction role config for specific message |
/reactionrole add <emoji> <role> | Add emoji-role mapping to current config |
/reactionrole remove <emoji> | Remove an emoji-role mapping |
/reactionrole list | Show all reaction role configs on the server |
/reactionrole enable <config_id> | Activate a reaction role configuration |
/reactionrole disable <config_id> | Deactivate a configuration |
/reactionrole delete <config_id> | Remove a reaction role configuration |
/reactionrole test <msg_id> | Test a configuration without assigning roles |
Choosing Emojis
Tips for selecting appropriate emojis for reaction roles:
Standard Emojis
Use universally recognized emojis that clearly indicate the role. Work on any server.
Examples: 🎮 Gaming, 🎨 Art, 🎵 Music, 📚 Study, ⚽ Sports
Custom Server Emojis
Use custom emojis from your server for branding. Must reference the server's emoji.
Examples: :custom_emoji: or your server's branded emojis
Emoji Best Practices
- ✓ Use emojis that are intuitive and related to the role
- ✓ Keep emojis consistent across your server
- ✓ Avoid animated emojis if you want broader compatibility
- ✓ Use 1 emoji per role (don't duplicate)
- ✗ Don't use too many emojis (limits user attention)
- ✗ Avoid confusing or ambiguous emojis
Configuration Examples
Real-world examples of reaction role setups:
Gaming Server Roles
Users can self-select which gaming communities they're part of
Language Selection
Perfect for international communities or servers with regional channels
Notification Opt-ins
Let users customize which notifications they receive
Skill Level Selection
Help users find peers at their skill level
Creating Reaction Role Messages
Tips for writing effective reaction role messages:
Clear Instructions
Start with a clear title and instructions. Explain what users get by reacting.
Example: "React below to get access to gaming channels!"
List Emoji-Role Mappings
Show each emoji and what role it assigns. Make it obvious and scannable.
🎮 = Gamer
🎨 = Artist
🎵 = Musician
Use Embeds
Create a rich embed with colors, fields, and formatting to make it visually appealing.
Pin Important Messages
Pin the reaction role message so users can always find it.
Advanced Features
Additional configuration options for reaction roles:
Mutually Exclusive Roles
Configure roles so users can only have one at a time. When they react to a new emoji, the old role is removed.
Use case: Skill levels (can't be Beginner AND Advanced simultaneously)
Cumulative Roles
Users can get multiple roles at once. Each emoji adds a role without removing others.
Use case: Interests (user can be Artist, Gamer, AND Musician)
Role Requirements
Require users to have certain roles before they can react for another role.
Use case: Only allow "Verified" users to access other roles
Role Removal on Unreact
Automatically remove roles when users remove their reaction. Can be disabled for important roles.
Use case: Temporary role assignments vs permanent ones
Permission Requirements
Bot permissions needed for reaction roles to work:
Troubleshooting
Common issues and solutions:
Reactions don't assign roles
Check that the bot has "Manage Roles" permission. Verify the emoji-role mapping is correct. Ensure the configuration is enabled.
Custom emoji not working
Custom emojis must be from the same server. The bot needs "Manage Emojis" permission to use custom emojis from other servers.
Roles not being removed when unreacting
Check if role removal is enabled in the configuration. Some roles may be set to not be removed on unreact.
"Role is above bot's highest role" error
The bot's role must be higher than the role it's trying to assign. Move the bot's role higher in the server role hierarchy.
Can't find the message ID
Enable Developer Mode in Discord User Settings (Appearance tab). Then right-click messages to copy their ID.
Tips & Best Practices
- • Use clear, descriptive emojis that relate to the roles
- • Create a dedicated channel for reaction role messages
- • Pin the reaction role message so it doesn't get lost in chat
- • Use embeds to make the message visually appealing
- • Add instructions above the emoji list explaining how it works
- • Keep the number of emojis reasonable (8-10 is a good limit)
- • Don't use duplicate emojis across different reaction role messages
- • Test each emoji-role mapping before going live
- • For large servers, consider using mutually exclusive role groups
- • Regularly clean up unused roles or reaction role configs
- • Use role colors to make roles visually distinctive in the member list
- • Update messages if roles change to keep users informed