Configuration

Reaction Roles uses one config file/interface named reactionroles. It contains two top-level blocks:

config for behavior and panel definitions
lang for user-facing messages

Plugin Settings

Option	Type	Default	Description
`config.enabled`	boolean	`true`	Master switch for the reaction role system.
`config.auto_remove_user_reactions`	boolean	`true`	Removes a user’s reaction after assigning a role for reaction-based panels.
`config.log_role_changes`	boolean	`false`	Sends role add/remove logs to `log_channel`.
`config.log_channel`	string	`""`	Channel ID for role-change logs.
`config.max_roles_per_user`	number	`0`	Maximum role count a user can have from a panel. `0` means unlimited.
`config.role_hierarchy_check`	boolean	`true`	Prevents assigning roles at or above the bot’s highest role.
`config.permission_bypass_roles`	string[]	`[]`	Role IDs that bypass role limits and hierarchy restrictions.
`config.panels`	object	`{}`	Named panel definitions.

Panel Object

Each key under config.panels is a panel name:


panels: {
  notifications: {
    type: "MIXED",
    channel_id: "123456789012345678",
    placeholder: "Choose your roles...",
    show_check_button: true,
    embed: {},
    selectOptions: [],
    buttons: [],
    reactionEmojis: [],
    subPanels: {}
  }
}

Field	Type	Description
`type`	string	Panel type: `MIXED`, `SELECT`, `BUTTON`, `REACT`, or `CATEGORY`.
`channel_id`	string	Discord channel ID where the panel is sent.
`placeholder`	string	Placeholder for dropdown/select menus.
`reset_reacts`	boolean	Legacy reaction reset setting.
`show_check_button`	boolean	Shows the “Check My Current Roles” button when supported.
`embed`	object	Discord embed displayed above the components.
`reactions`	array	Legacy entry array used by `SELECT`, `BUTTON`, `REACT`, and `CATEGORY`.
`selectOptions`	array	`MIXED` select-menu entries.
`buttons`	array	`MIXED` button entries.
`reactionEmojis`	array	`MIXED` emoji reaction entries.
`subPanels`	object	Ephemeral child panels opened from buttons/select options.
`categories`	array	Legacy category panel definitions.

Embed Object

Field	Type	Description
`embed.title`	string	Embed title. Discord markdown is supported.
`embed.description`	string or string[]	Main embed body. Arrays are joined with new lines.
`embed.color`	string	Hex embed color, such as `#1769FF`.
`embed.image`	string	Large image URL.
`embed.thumbnail`	string	Thumbnail URL.
`embed.footer.text`	string	Footer text.
`embed.footer.icon`	string	Footer icon URL.
`embed.author.text`	string	Author name.
`embed.author.icon`	string	Author icon URL.

Role Entry Object

Role entries are used in reactions, selectOptions, buttons, and reactionEmojis.

Field	Type	Description
`enabled`	boolean	If false, the entry is ignored. Defaults to enabled.
`type`	string	`role` for role toggles, or `sub_panel` to open a sub-panel.
`name`	string	Label shown in buttons/selects and used in responses.
`emoji`	string	Emoji shown in the UI or used as the reaction trigger.
`style`	string	Button style: `Primary`, `Secondary`, `Success`, or `Danger`.
`description`	string	Select-menu description or internal description.
`role_id`	string	Discord role ID to add/remove. Required for role entries.
`sub_panel_id`	string	Sub-panel key to open. Required for `sub_panel` entries.

Sub-Panel Object

Sub-panels are temporary, private panels shown ephemerally when a user clicks a linked button or select option.


subPanels: {
  games: {
    name: "Game Roles",
    prompt: "Pick your game roles below:",
    placeholder: "Choose games...",
    embed: {
      title: "Game Roles",
      description: ["Choose the games you play."],
      color: "#5865F2"
    },
    buttons: [],
    selectOptions: []
  }
}

Field	Type	Description
`name`	string	Internal/display name for the sub-panel.
`prompt`	string	Text shown above the sub-panel components.
`placeholder`	string	Select-menu placeholder.
`embed`	object	Optional embed shown inside the ephemeral response.
`buttons`	array	Button role entries or links to deeper sub-panels.
`selectOptions`	array	Select-menu role entries or links to deeper sub-panels.

Language Settings

Key	Description
`role_added`	Message after adding one role. Uses `{role_name}`.
`role_removed`	Message after removing one role. Uses `{role_name}`.
`roles_updated`	Header after select-menu changes.
`roles_added`	Added roles line. Uses `{role_names}`.
`roles_removed`	Removed roles line. Uses `{role_names}`.
`no_changes`	Response when a selection did not change roles.
`member_not_found`	Error when member data cannot be found.
`role_not_found`	Error when a configured role no longer exists.
`panel_not_found`	Error when a panel key cannot be found.
`category_not_found`	Error for missing category/sub-panel targets.
`permission_denied`	Error when the user cannot self-assign a role.
`role_hierarchy_error`	Error when the bot cannot assign a role due to hierarchy.
`max_roles_reached`	Error when max role limit is reached. Uses `{max_roles}`.
`bot_permission_error`	Generic bot role-permission failure.
`interaction_error`	Generic interaction failure.
`log_title`	Role-change log embed title.
`log_user_field`	Role-change log user field label.
`log_role_field`	Role-change log role field label.
`log_action_field`	Role-change log action field label.
`log_action_added`	Role-change log value for add actions.
`log_action_removed`	Role-change log value for remove actions.
`plugin_disabled`	Startup/command disabled message.
`plugin_loaded`	Startup loaded message.
`panel_exists`	Startup message when a valid panel already exists.
`panel_sent`	Startup message when a panel is sent.
`channel_not_found`	Startup error for missing channel IDs.
`current_roles_title`	Header for the check-current-roles response.
`current_roles_from_panel`	Current roles line. Uses `{roles}`.
`current_roles_none`	Text when the user has none of the panel roles.
`check_roles_tip`	Tip under the current roles response.
`select_tip`	Tip after select-menu updates.
`default_placeholder`	Fallback select placeholder.
`no_description`	Fallback description text.
`subpanel_prompt`	Fallback prompt for sub-panels.
`subpanel_closed`	Message when a sub-panel is closed.

Example Mixed Panel


notifications: {
  type: "MIXED",
  channel_id: "123456789012345678",
  placeholder: "Choose notification roles...",
  show_check_button: true,
  embed: {
    title: "Choose Your Roles!",
    description: [
      "> Server Updates - Get notified about server updates.",
      "> Giveaways - Get pinged for giveaways."
    ],
    color: "#1769FF"
  },
  selectOptions: [
    {
      enabled: true,
      type: "role",
      name: "Server Updates",
      emoji: "📢",
      description: "Get notified about updates.",
      role_id: "123456789012345678"
    }
  ],
  buttons: [],
  reactionEmojis: [],
  subPanels: {}
}