Setup Guide

Complete setup guide for Role Reactor Bot - from installation to creating your first role messages

Quick Start

Formatting Note: When creating role strings, avoid extra spaces around commas and ensure each emoji is unique. Use 🎮:Gaming,🎨:Art not 🎮:Gaming, 🎨:Art.

Invite the Bot

Add Role Reactor Bot to your server

Ensure the following permissions are granted:

Manage Roles, Manage Messages, Send Messages, Add Reactions, Read Message History, View Channel, Embed Links, Manage Server, Use External Emojis

Create Your First Role Message

/role-reactions setup title:Server Roles description:Choose your roles below! roles:🎮:Gaming,📚:Books,🎵:Music

Verify Functionality

Test the role message by clicking reactions to confirm roles are assigned and removed correctly.

Setup complete. You now have a functional role system. Continue reading for advanced configuration options.

Permission Requirements

Required Permissions

The bot requires the following permissions to function:

Manage Roles

Assign and remove roles from members

Manage Messages

Manage role-reaction messages

Add Reactions

Add emoji reactions to messages

Read Message History

Monitor reaction events and read channel history

View Channel

Access channels where the bot operates

Send Messages

Create role selection messages and respond to commands

Embed Links

Create rich embedded messages

Manage Server

Manage server settings and configurations

Use External Emojis

Use emojis from other servers

Permission Configuration

During Invitation: Select all required permissions when inviting the bot
Post-Installation: Verify bot permissions in Server Settings > Roles
Role Position: Ensure the bot's role is positioned above any roles it manages

Important: The bot can only manage roles that are positioned below its own role in the server hierarchy.

Creating Role Messages

Basic Role Message

Basic role list: /role-reactions setup title:Choose Your Roles description:React to get roles! roles:🎮:Gaming,📚:Reading,🎵:Music,🎨:Art Output: Choose Your Roles React to get roles! 🎮 📚 🎵 🎨

Organized with categories: bash /role-reactions setup title:Game Roles description:Choose your favorite games! roles:🔴:Valorant,⚡:Apex Legends,⚔️:League of Legends Output: Game Roles Choose your favorite games! 🔴 ⚡ ⚔️

Full customization: bash /role-reactions setup title:🌟 Community Roles description:**Welcome!** Choose your roles below.\n\n*You can select multiple roles.* roles:#Gaming 🎮\n🖥️:PC Gaming,🎮:Console,📱:Mobile\n#Creative 🎨\n🎨:Art,📸:Photo,🎵:Music

Category Organization

Organize roles into categories for improved user experience:

Category Header Begin with #Category Name to create a section header

Add Roles List roles under each category: emoji:role1,emoji:role2

Multiple Categories Separate categories with \n for new lines

Example Structure:

#Gaming Platforms
🖥️:PC Gaming,🎮:Console Gaming,📱:Mobile Gaming
#Notifications
📢:Announcements,🎉:Events,📰:News
#Interests
🎨:Art,📚:Books,🎵:Music

Role Message Management

Managing Existing Messages

Edit Message

/role-reactions update - Update title, description, or roles

Delete Message

/role-reactions delete - Remove a role message

List Messages

/role-reactions list - View all role messages

Refresh Reactions

Contact support - Fix broken reactions

Role Color Configuration

Setting Role Colors:

Roles are created through Discord's server settings. The bot can only manage existing roles.

Navigate to Server Settings > Roles
Create new roles with your desired colors
Use the bot to assign these roles via reactions

Color Guidelines:

Use hex color codes (#FF0000) for precise control
Group related roles in similar color families
Ensure sufficient contrast for readability
Consider colorblind accessibility

Server Organization

Recommended Channel Structure

📋 INFORMATION
├── 📖 rules
├── 📢 announcements
└── 🎭 get-roles

💬 GENERAL
├── 💬 general-chat
├── 🎮 gaming
└── 🎵 music

Role Channel Best Practices

Recommendation: Create a dedicated #get-roles channel for optimal user experience.

Channel Configuration:

Create a channel named #get-roles or #roles
Configure permissions (everyone can view, limited sending)
Pin important role messages
Add channel description explaining reaction usage

Channel Description Example:

🎭 Role Selection

React to the messages below to get roles!
• Click an emoji to get that role
• Click again to remove the role
• You can have multiple roles
• Ask in #general if you need help

Advanced Configuration

Role Hierarchy Management

Important Rules:

Bot's role must be positioned above managed roles
Higher roles in the list have more permissions
Exercise caution with administrative roles

Hierarchy Setup:

Navigate to Server Settings > Roles
Drag the bot's role above any roles it should manage
Arrange other roles by importance
Test role assignment to verify functionality

Multiple Role Messages

For larger servers, create multiple focused role messages:

Message 1: Essential Roles bash /role-reactions setup title:Essential Roles roles:📢:Announcements,🎉:Events,💬:General Chat Message 2: Interests bash /role-reactions setup title:Your Interests roles:#Hobbies\n🎮:Gaming,📚:Reading,🎵:Music,🎨:Art

Message 1: Gaming Platforms bash /role-reactions setup title:Gaming Platforms roles:🖥️:PC,🎮:PlayStation,🎯:Xbox,📱:Mobile,🕹️:Nintendo Message 2: Game Types bash /role-reactions setup title:Game Genres roles:#Genres\n🔫:FPS,⚔️:RPG,🏎️:Racing,🎲:Strategy,👥:MMO Message 3: Activity bash /role-reactions setup title:Playstyle roles:#Playstyle\n🏆:Competitive,🎯:Casual,👥:Looking for Group

Message 1: Subjects bash /role-reactions setup title:Study Subjects roles:#Subjects\n📊:Math,🔬:Science,📚:English,🏛️:History Message 2: Study Groups bash /role-reactions setup title:Study Style roles:#Study Style\n👥:Group Study,🤫:Solo Study,📅:Study Schedule

Troubleshooting

Common Issues

Bot Not Responding - Verify bot permissions - Check bot role position - Confirm bot is online

Roles Not Being Assigned - Verify role hierarchy (bot role above target roles) - Confirm role names match exactly - Test with a simple role first

Reactions Not Working - Contact support to fix reactions - Verify emojis are from the server or Unicode - Confirm bot can add reactions in the channel

Additional Support

If issues persist:

Review the Troubleshooting section for detailed solutions
Join our support server for community assistance
Report bugs through our GitHub issues page

Setup Complete: Your Role Reactor Bot is now configured and ready to use. Visit the Examples section for inspiration on creating engaging role systems for your community.