Reaction Roles

A comprehensive guide to setting up and configuring reaction role panels in DrakoBot.

Overview

Reaction roles allow members to self-assign roles by clicking buttons, selecting from dropdowns, or reacting with emojis. DrakoBot supports three panel types with advanced features like role limits, conditions, and auto-granting.

---

Configuration Location

Edit the reaction roles in: config/modules/roles.yml

All panels go under the ReactionRoles: section.

---

Panel Types

Type	Description	Best For
BUTTON	Interactive buttons below the message	2-5 roles, clean look
SELECT	Dropdown menu	5+ roles, saves space
REACT	Traditional emoji reactions	Simple setups, legacy style

---

Basic Setup

Minimal Configuration

ReactionRoles:
  Enabled: true

  PanelName:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID"]
    
    Reactions:
      - Name: "Role Name"
        Emoji: "📢"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "Role description"
        RemoveRoles: []

Required Fields:

• type - Panel type (BUTTON, SELECT, or REACT)

• ChannelID - Where to post the panel (supports arrays for multi-guild)

• Reactions - Array of role configurations

Per-Reaction Fields:

• Name - Display name for the role

• Emoji - Emoji to show

• RoleID - Role ID to assign (supports arrays for multi-guild)

• RemoveRoles - Roles to remove when this is selected (optional)

Button Styles: Primary (blue), Success (green), Danger (red), Secondary (gray)

---

Advanced Features

Panel-Level Options

PanelName:
  type: "BUTTON"
  ChannelID: ["CHANNEL_ID"]
  
  MaxSelections: 3
  RequiredRoles: ["VERIFIED_ROLE_ID"]
  resetReacts: true
  UseComponentsV2: true

Options:

• MaxSelections - Limit how many roles can be selected from this panel

• RequiredRoles - Member must have ALL these roles to use the panel

• resetReacts - Remove user's reaction after clicking (REACT type only)

• UseComponentsV2 - Enable modern Discord UI components

Per-Role Advanced Options

Reactions:
  - Name: "VIP Role"
    Emoji: "💎"
    Style: "Primary"
    RoleID: ["ROLE_ID"]
    RemoveRoles: ["BASIC_ROLE_ID", "OTHER_ROLE_ID"]
    GrantRoles: ["CATEGORY_ROLE_ID", "PERK_ROLE_ID"]
    Description: "VIP membership"
    Conditions:
      RequiredRoles: ["VERIFIED_ID", "LEVEL_10_ID"]
      ExcludedRoles: ["BANNED_ID"]
      ForbiddenRoles: ["TRIAL_ID"]

• RemoveRoles - Automatically removes these roles when selected (e.g., remove "Blue" when selecting "Red")

• GrantRoles - Automatically grants additional roles (e.g., give "Has Color Role" category separator)

Conditions:

• RequiredRoles - Must have ALL of these to select this role

• ExcludedRoles - Cannot select if member has ANY of these

• ForbiddenRoles - Can only select if member has NONE of these

---

Quick Examples

1

Simple Notification Roles (Buttons)

ReactionRoles:
  Enabled: true

  Notifications:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID"]
    
    Embed:
      Title: "📢 Notification Roles"
      Description:
        - "Click a button to toggle notification roles."
        - "You can select multiple roles!"
      Color: "#5865F2"
      Thumbnail: "https://i.imgur.com/w5XxKpc.png"
    
    Reactions:
      - Name: "Announcements"
        Emoji: "📢"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "Server announcements"
        RemoveRoles: []
      - Name: "Events"
        Emoji: "🎉"
        Style: "Success"
        RoleID: ["ROLE_ID"]
        Description: "Event notifications"
        RemoveRoles: []
      - Name: "Updates"
        Emoji: "📰"
        Style: "Secondary"
        RoleID: ["ROLE_ID"]
        Description: "Bot & server updates"
        RemoveRoles: []

2

Color Roles with Limits (Select Menu)

ReactionRoles:
  Enabled: true

  ColorRoles:
    type: "SELECT"
    ChannelID: ["CHANNEL_ID"]
    MaxSelections: 1
    
    Embed:
      Title: "🎨 Color Roles"
      Description:
        - "Choose ONE color for your name!"
      Color: "#FF5555"
    
    Reactions:
      - Name: "Red"
        Emoji: "🔴"
        Style: "Danger"
        RoleID: ["RED_ROLE_ID"]
        Description: "Red name color"
        RemoveRoles: ["BLUE_ROLE_ID", "GREEN_ROLE_ID", "YELLOW_ROLE_ID"]
      - Name: "Blue"
        Emoji: "🔵"
        Style: "Primary"
        RoleID: ["BLUE_ROLE_ID"]
        Description: "Blue name color"
        RemoveRoles: ["RED_ROLE_ID", "GREEN_ROLE_ID", "YELLOW_ROLE_ID"]
      - Name: "Green"
        Emoji: "🟢"
        Style: "Success"
        RoleID: ["GREEN_ROLE_ID"]
        Description: "Green name color"
        RemoveRoles: ["RED_ROLE_ID", "BLUE_ROLE_ID", "YELLOW_ROLE_ID"]
      - Name: "Yellow"
        Emoji: "🟡"
        Style: "Secondary"
        RoleID: ["YELLOW_ROLE_ID"]
        Description: "Yellow name color"
        RemoveRoles: ["RED_ROLE_ID", "BLUE_ROLE_ID", "GREEN_ROLE_ID"]

3

Pronoun Roles (Buttons)

ReactionRoles:
  Enabled: true

  Pronouns:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID"]
    
    Embed:
      Title: "🌈 Pronoun Roles"
      Description:
        - "Select your pronouns! You can pick multiple."
      Color: "#FFA500"
    
    Reactions:
      - Name: "He/Him"
        Emoji: "👨"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "He/Him pronouns"
        RemoveRoles: []
      - Name: "She/Her"
        Emoji: "👩"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "She/Her pronouns"
        RemoveRoles: []
      - Name: "They/Them"
        Emoji: "⚧️"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "They/Them pronouns"
        RemoveRoles: []
      - Name: "Any Pronouns"
        Emoji: "✨"
        Style: "Secondary"
        RoleID: ["ROLE_ID"]
        Description: "Any pronouns"
        RemoveRoles: []

4

Gaming Roles with Auto-Grant (Select)

ReactionRoles:
  Enabled: true

  GamingRoles:
    type: "SELECT"
    ChannelID: ["CHANNEL_ID"]
    MaxSelections: 3
    
    Embed:
      Title: "🎮 Gaming Roles"
      Description:
        - "Select up to 3 games you play!"
        - "You'll get access to game channels."
      Color: "#7289DA"
    
    Reactions:
      - Name: "Valorant"
        Emoji: "🎯"
        Style: "Primary"
        RoleID: ["VALORANT_ROLE_ID"]
        Description: "Valorant player"
        RemoveRoles: []
        GrantRoles: ["GAMER_ROLE_ID"]
      - Name: "League of Legends"
        Emoji: "⚔️"
        Style: "Success"
        RoleID: ["LOL_ROLE_ID"]
        Description: "LoL player"
        RemoveRoles: []
        GrantRoles: ["GAMER_ROLE_ID"]
      - Name: "Minecraft"
        Emoji: "🟩"
        Style: "Success"
        RoleID: ["MINECRAFT_ROLE_ID"]
        Description: "Minecraft player"
        RemoveRoles: []
        GrantRoles: ["GAMER_ROLE_ID"]
      - Name: "Fortnite"
        Emoji: "🏆"
        Style: "Primary"
        RoleID: ["FORTNITE_ROLE_ID"]
        Description: "Fortnite player"
        RemoveRoles: []
        GrantRoles: ["GAMER_ROLE_ID"]

5

VIP Roles with Requirements (Buttons)

ReactionRoles:
  Enabled: true

  VIPPerks:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID"]
    RequiredRoles: ["VIP_ROLE_ID"]
    
    Embed:
      Title: "💎 VIP Perks"
      Description:
        - "Exclusive roles for VIP members!"
        - "Must have VIP role to access."
      Color: "#FFD700"
    
    Reactions:
      - Name: "Early Access"
        Emoji: "⚡"
        Style: "Primary"
        RoleID: ["EARLY_ACCESS_ROLE_ID"]
        Description: "Early feature access"
        RemoveRoles: []
        Conditions:
          RequiredRoles: ["VIP_ROLE_ID"]
          ExcludedRoles: ["BANNED_ROLE_ID"]
      - Name: "Custom Color"
        Emoji: "🎨"
        Style: "Success"
        RoleID: ["CUSTOM_COLOR_ROLE_ID"]
        Description: "Custom name color"
        RemoveRoles: []
        Conditions:
          RequiredRoles: ["VIP_ROLE_ID"]
      - Name: "VIP Voice"
        Emoji: "🎤"
        Style: "Primary"
        RoleID: ["VIP_VOICE_ROLE_ID"]
        Description: "VIP voice channels"
        RemoveRoles: []
        Conditions:
          RequiredRoles: ["VIP_ROLE_ID"]

6

Region Selection (Reactions)

ReactionRoles:
  Enabled: true

  Regions:
    type: "REACT"
    resetReacts: true
    ChannelID: ["CHANNEL_ID"]
    
    Embed:
      Title: "🌍 Region Selection"
      Description:
        - "React with your region to get regional announcements."
      Color: "#3498DB"
    
    Reactions:
      - Name: "North America"
        Emoji: "🇺🇸"
        Style: "Primary"
        RoleID: ["NA_ROLE_ID"]
        Description: "North America"
        RemoveRoles: []
      - Name: "Europe"
        Emoji: "🇪🇺"
        Style: "Primary"
        RoleID: ["EU_ROLE_ID"]
        Description: "Europe"
        RemoveRoles: []
      - Name: "Asia"
        Emoji: "🇯🇵"
        Style: "Primary"
        RoleID: ["ASIA_ROLE_ID"]
        Description: "Asia"
        RemoveRoles: []
      - Name: "Oceania"
        Emoji: "🇦🇺"
        Style: "Primary"
        RoleID: ["OCE_ROLE_ID"]
        Description: "Oceania"
        RemoveRoles: []

---

ComponentsV2 (Modern UI)

ComponentsV2 provides a modern Discord UI experience with rich formatting and media support.

Basic ComponentsV2 Example

ReactionRoles:
  Enabled: true

  ModernPanel:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID"]
    UseComponentsV2: true
    
    ComponentsV2:
      Components:
        - Type: "container"
          AccentColor: "#5865F2"
          Components:
            - Type: "section"
              Text:
                Content: "**ROLE SELECTION**\n\nSelect your preferences below.\n\n```📢  Announcements  ·  Server updates\n🎉  Events         ·  Event pings\n📰  News           ·  News updates```\n\n-# Click buttons below  ·  Drako Bot"
              Accessory:
                Type: "thumbnail"
                Media:
                  URL: "https://i.imgur.com/w5XxKpc.png"
    
    Reactions:
      - Name: "Announcements"
        Emoji: "📢"
        Style: "Primary"
        RoleID: ["ROLE_ID"]
        Description: "Server announcements"
        RemoveRoles: []

ComponentsV2 Structure:

• Type: "container" - Main container

• AccentColor - Hex color for the accent bar

• Type: "section" - Content section

• Text.Content - Markdown-formatted content

• Accessory.Type: "thumbnail" - Optional thumbnail image

---

Multi-Guild Support

All ID fields support arrays for multi-guild setups:

ReactionRoles:
  Enabled: true

  MultiGuildPanel:
    type: "BUTTON"
    ChannelID: ["CHANNEL_ID_GUILD1", "CHANNEL_ID_GUILD2"]
    
    Reactions:
      - Name: "Member"
        Emoji: "✅"
        Style: "Success"
        RoleID: ["ROLE_ID_GUILD1", "ROLE_ID_GUILD2"]
        Description: "Member role"
        RemoveRoles: []

The bot will match the channel ID's index with the role ID's index (first channel uses first role, second channel uses second role).

---

How to Deploy Panels

1. Edit config/modules/roles.yml

2. Add or modify panels under ReactionRoles:

3. Restart the bot completely

4. Panels will automatically appear in their configured channels

Note: Any time you edit a panel configuration, you must restart the bot for changes to take effect.

---

Troubleshooting

❌ Buttons/Reactions Not Working

Check:

• ReactionRoles.Enabled: true is set

• Bot has Manage Roles permission

• Bot's highest role is above all roles being assigned

• Member meets panel's RequiredRoles (if set)

• Member meets reaction's Conditions (if set)

❌ Panel Not Appearing

Solutions:

• Verify ChannelID is correct (right-click channel → Copy ID)

• Ensure Developer Mode is enabled in Discord settings

• Restart the bot completely

• Check bot has Send Messages and Embed Links permissions in channel

❌ Roles Not Being Assigned

Check:

• Replace all ROLE_ID placeholders with actual role IDs

• Bot's role is higher in the role hierarchy than assigned roles

• Bot has Manage Roles permission

• Roles aren't marked as "managed" (bot roles, booster roles can't be assigned)

❌ "Max Selections Reached" Error

Solution:

• Remove some roles first, then add new ones

• Or increase MaxSelections value

❌ "Missing Required Roles" Error

Check:

• Member has all roles listed in panel's RequiredRoles

• Member has all roles listed in reaction's Conditions.RequiredRoles

❌ "Excluded By Role" Error

Solution:

• Member has a role in ExcludedRoles or ForbiddenRoles

• Remove the conflicting role first

❌ Multiple Panels Interfering

Solution:

• Each panel must have a unique name (e.g., Panel1, Panel2, not both named Roles)

• Use descriptive names like ColorRoles, NotificationRoles, GamingRoles

❌ Panel Posted in Wrong Channel

Solutions:

• Double-check ChannelID value

• For multi-guild: ensure channel IDs are in correct order matching role IDs

• Delete old panel messages manually if needed

---

Best Practices

• Use descriptive panel names (ColorRoles not Panel1)

• Set MaxSelections for exclusive role categories

• Use RemoveRoles to prevent conflicting role combinations

• Add RequiredRoles to panels for verified members only

• Use ComponentsV2 for modern, polished appearance

• Use appropriate button styles (Primary/Success/Danger/Secondary)

---

Getting Role & Channel IDs

1. Enable Developer Mode in Discord:

   • User Settings → App Settings → Advanced → Developer Mode: ON

2. Get Role ID:

   • Server Settings → Roles → Right-click role → Copy ID

3. Get Channel ID:

   • Right-click channel → Copy ID