Reaction Roles

The Reaction Roles module allows users to self-assign roles by interacting with bot messages — using buttons, a dropdown menu, or emoji reactions.

Enabling the Module

1. Dashboard → Your server → toggle Reaction Roles
2. Click Edit to manage configurations
3. Add a new configuration (panel) or edit an existing one
4. Deploy the configuration to a selected channel

Interaction Modes

Mode	Description
buttons	Buttons under the message — one click = toggle role
dropdown	Dropdown menu with multiple selection
reactions	Classic emoji reactions under the message

Behavior

Mode	Description
toggle	Clicking adds the role, clicking again removes it
add_only	Clicking only adds the role — it cannot be removed this way

Configuration

Each reaction roles configuration (panel) contains:

Option	Type	Description
mode	string	Mode: buttons, dropdown, reactions
behavior	string	Behavior: toggle, add_only
channel_id	string	Target channel
embed	object	Embed configuration (title, description, color)
role_mappings	array	List of mappings: emoji → role
max_roles	number	Max roles to select in dropdown (default 25)
placeholder	string	Placeholder text in dropdown

role_mappings Structure

[
  {
    "role_id": "123456789",
    "emoji": "🎮",
    "label": "Gamer"
  },
  {
    "role_id": "987654321",
    "emoji": "🎵",
    "label": "Music Lover"
  }
]

Dashboard — Configuration

The Reaction Roles edit panel displays a card grid — one card per configuration:

Each card contains:

• Embed preview with colored badges
• Status: Deployed / Not deployed
• Mode (buttons/dropdown/reactions)
• Edit and Delete buttons

Creating a new configuration

1. Click the button to add a new configuration
2. Fill in the embed (title, description, color)
3. Add role mappings (emoji + role + label)
4. Select the mode and behavior
5. Save and deploy

Auto-redeploy

When you edit an already deployed configuration and save changes, the bot automatically edits the existing Discord message — updating the embed and components (buttons/dropdown). You don't need to manually delete and redeploy.

Listened Events

Event	Action
on_interaction	Handles button clicks and dropdown selections
on_raw_reaction_add	Handles reaction additions (reactions mode)
on_raw_reaction_remove	Handles reaction removals (reactions mode, toggle only)

Process Flow

Buttons Mode

1. User clicks a button
2. Bot parses custom_id (format: rr:{role_id})
3. Checks if the bot can manage that role (hierarchy)
4. Toggle: if user has the role → removes it; if not → adds it
5. Sends an ephemeral response
6. Logs the change in the Logs module

Dropdown Mode

1. User selects roles from the menu (can select multiple)
2. Bot compares selected roles with currently held ones
3. Adds missing ones, removes deselected ones (in toggle mode)
4. Sends a change summary

Reactions Mode

1. User adds an emoji reaction
2. Bot maps emoji to role_id
3. Adds the role to the user
4. On reaction removal (toggle) — removes the role

Deployed Message Tracking

Deployed messages are saved in the reaction_role_messages table:

• message_id — Discord message ID
• config_index — configuration index in the array

The bot loads this data on startup and keeps it in memory for fast interaction routing.

Logging

Role changes are logged by Logs under the reaction_roles category:

• Role Added — role addition (with method info: button/dropdown/reaction)
• Role Removed — role removal
• Error — missing role (role was deleted from the server after configuration)

Error Handling

• Missing role — if a configured role doesn't exist, the user gets an ephemeral message "This role no longer exists. Please contact an administrator." + error log
• Role hierarchy — if the bot can't manage the role, it displays a message about needing to move the bot role higher

Tips

Best practices

• Use Buttons mode for a small number of roles (1–5) — most intuitive
• Use Dropdown mode for many roles (6+) — takes less space
• Reactions mode is legacy — buttons/dropdown are more reliable
• Set clear emojis and labels so users know what they're choosing
• Check role hierarchy after configuration — the bot role must be higher than self-assign roles

Important

After deleting a role from the Discord server, the reaction roles configuration doesn't update automatically. Remove the non-existent role from the configuration in the dashboard to avoid errors.