# Reaction Roles

## 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

{% code expandable="true" %}

```yaml
ReactionRoles:
  Enabled: true

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

{% endcode %}

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

```yaml
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

```yaml
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

{% stepper %}
{% step %}

### Simple Notification Roles (Buttons)

{% code expandable="true" %}

```yaml
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: []
```

{% endcode %}
{% endstep %}

{% step %}

### Color Roles with Limits (Select Menu)

{% code expandable="true" %}

```yaml
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"]
```

{% endcode %}
{% endstep %}

{% step %}

### Pronoun Roles (Buttons)

{% code expandable="true" %}

```yaml
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: []
```

{% endcode %}
{% endstep %}

{% step %}

### Gaming Roles with Auto-Grant (Select)

{% code expandable="true" %}

```yaml
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"]
```

{% endcode %}
{% endstep %}

{% step %}

### VIP Roles with Requirements (Buttons)

{% code expandable="true" %}

```yaml
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"]
```

{% endcode %}
{% endstep %}

{% step %}

### Region Selection (Reactions)

{% code expandable="true" %}

```yaml
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: []
```

{% endcode %}
{% endstep %}
{% endstepper %}

***

## ComponentsV2 (Modern UI)

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

### Basic ComponentsV2 Example

{% code expandable="true" %}

````yaml
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: []
````

{% endcode %}

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:

{% code expandable="true" %}

```yaml
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: []
```

{% endcode %}

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

<details>

<summary>❌ Buttons/Reactions Not Working</summary>

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)

</details>

<details>

<summary>❌ Panel Not Appearing</summary>

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

</details>

<details>

<summary>❌ Roles Not Being Assigned</summary>

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)

</details>

<details>

<summary>❌ "Max Selections Reached" Error</summary>

Solution:

* Remove some roles first, then add new ones
* Or increase `MaxSelections` value

</details>

<details>

<summary>❌ "Missing Required Roles" Error</summary>

Check:

* Member has all roles listed in panel's `RequiredRoles`
* Member has all roles listed in reaction's `Conditions.RequiredRoles`

</details>

<details>

<summary>❌ "Excluded By Role" Error</summary>

Solution:

* Member has a role in `ExcludedRoles` or `ForbiddenRoles`
* Remove the conflicting role first

</details>

<details>

<summary>❌ Multiple Panels Interfering</summary>

Solution:

* Each panel must have a **unique name** (e.g., `Panel1`, `Panel2`, not both named `Roles`)
* Use descriptive names like `ColorRoles`, `NotificationRoles`, `GamingRoles`

</details>

<details>

<summary>❌ Panel Posted in Wrong Channel</summary>

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

</details>

***

## 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