# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.drakodevelopment.net/moderation-and-roles/reaction-roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.