Quick overview — what reaction roles provide

Reaction Roles let server members self-assign (or remove) roles by interacting with a message UI (emoji reactions or select menus). Use reaction role messages to provide pings, access roles, interest groups, event opt-ins, and more — all without manual staff intervention. The system supports multi-select panels, previews in the dashboard, and push/sync flows so staff can stage changes before publishing.

Command reference

Below each command you’ll find Purpose, Syntax / options, Examples, Who can run it, and Notes / tips.

/reactionrole create

Purpose — Create a new reaction-role message (panel). Use this to post a message or select-menu panel in a channel and populate it with emoji-role options.

Syntax / options — The command prompts for a title, channel, and then per-option details (emoji, role, description). The dashboard builder provides the same fields (title, description, channel, and role options).
Example

/reactionrole create title:"Pick your pings" channel:#lounge
# then follow the interactive prompts to add emoji + role + description for each option

Who can run it — Staff/managers as configured in Command Permissions.
Notes / tips — Create short helper descriptions for each role option to help members choose. The dashboard shows a Panel Preview so you can verify ordering and labels before pushing.

/reactionrole add <emoji> <role>

Purpose — Add a new emoji → role mapping to an existing reaction-role message (panel).

Syntax

/reactionrole add message_id:<message_id> emoji:🔔 role:@Pings

Examples

/reactionrole add message_id:123456789012345678 emoji:🎮 role:@Matchmaking

Who can run it — Staff / panel editors.
Notes / tips — Use the message ID of the panel message. If the panel uses select menus instead of reactions, the add flow will append a select option. If using external emojis, ensure the bot can use them (server must allow the emoji).

/reactionrole remove <emoji>

Purpose — Remove an emoji-role pair from a reaction-role message.

Syntax

/reactionrole remove message_id:<message_id> emoji:🔔

Examples

/reactionrole remove message_id:123456789012345678 emoji:🎮

Who can run it — Staff / panel editors.
Notes / tips — Removing an option will stop new members from toggling that role via the panel; it does not automatically strip the role from members who already have it (use role management commands if you need to cleanup).

/reactionrole delete

Purpose — Deletes a reaction-role message and removes its mappings from the persisted config.

Syntax

/reactionrole delete message_id:<message_id>

Examples

/reactionrole delete message_id:123456789012345678

Who can run it — Staff / managers.
Notes / tips — This removes the panel and deletes the stored mapping; it’s irreversible from the dashboard unless you recreate it.

/reactionrole list

Purpose — List all configured reaction-role messages and their emoji → role mappings.

Syntax

/reactionrole list

Examples

/reactionrole list

Who can run it — Staff.
Notes / tips — Useful for audits and to find the message IDs needed for edits or deletes.

/reactionrole edit <message_id>

Purpose — Edit the content of a reaction-role message or change its emoji-role mappings.

Syntax

/reactionrole edit message_id:<message_id>
# interactive prompts to change text, reorder options, add/remove mappings, etc.

Examples

/reactionrole edit message_id:123456789012345678

Who can run it — Staff / panel editors.
Notes / tips — The edit flow can update the message text, option labels, or the role tied to an emoji. Use it to correct wording, reorder items, or swap roles without deleting the whole panel.

/reactionrole panel

Purpose — Send a predefined panel of roles for users to select from (quickly post a saved role palette).

Syntax

/reactionrole panel name:<saved_panel_name> channel:#lounge

Examples

/reactionrole panel name:"LFG Roles" channel:#lounge

Who can run it — Staff.
Notes / tips — The dashboard can store presets or let you create a palette visually; /reactionrole panel posts a predefined palette message so staff can reuse common role sets.

/reactionrole toggle <message_id>

Purpose — Temporarily enable or disable a reaction-role message without deleting it.

Syntax

/reactionrole toggle message_id:<message_id> mode:enable|disable

Examples

/reactionrole toggle message_id:123456789012345678 mode:disable
/reactionrole toggle message_id:123456789012345678 mode:enable

Who can run it — Staff / panel managers.
Notes / tips — Use disable to prevent further role changes while you perform maintenance or reorganize options. The panel remains in storage so you can re-enable it later.

/reactionrole setup

Purpose — Run a guided setup wizard for new reaction-role panels and recommended permissions.

Syntax

/reactionrole setup

Examples

/reactionrole setup

Who can run it — Server admins or staff with setup privileges.
Notes / tips — The setup wizard helps choose a channel, builds a starter panel, and explains the required bot permissions and role positioning so assignments will succeed.

Permissions & Bot requirements

To create and operate reaction-role panels the bot needs:

• Manage Roles — to assign and remove roles to members.

• Manage Messages / Add Reactions — if using reaction-based panels the bot must be able to add and remove reaction emojis.

• Use External Emojis — if panel uses emojis from other servers.

• Read Message History / Send Messages / Embed Links — for posting panels and auditing.

• The bot’s role must be positioned above any roles it needs to assign. If it’s below the target role, assignments will fail.

Staff running commands need appropriate dashboard Command Permissions (Manager or Custom roles). Use the dashboard’s Command Permissions page to configure who can create/edit/delete reaction-role messages.

Persistence & syncing

Reaction-role mappings are stored on disk so they survive restarts. The dashboard notes that role IDs are persisted in data/reactionRoles.json. This means panels and mappings remain valid after bot restarts, and the dashboard can re-sync or pull existing panels by message ID.

Best practices & tips

• Keep panels short and focused. Limit each panel to a handful of roles to keep the message scannable.

• Use clear labels & helpers. Add a short description per option (e.g., “Queue nights & scrims”) so members understand what each role means.

• Prefer select-menus for many roles. If you have many roles, select menus are friendlier than dozens of reaction emojis.

• Avoid pinging large roles on the panel itself; use a small @role (like @Events) for event opt-ins.

• Test with staff first. Use the dashboard Preview to verify layout and emoji rendering (desktop vs mobile).

• External emojis: If you use an emoji from another server, ensure the bot can use it (and that the server allows it).

• Re-sync when needed: If someone manually edited the message in Discord, use /reactionrole list and /reactionrole edit (or dashboard sync) to reconcile the stored mapping with the live message.

Troubleshooting

• Role assignment fails: Check that the bot has Manage Roles and that the bot role is higher in the role list than the target role.

• Emoji not recognized / external emoji not usable: Verify the emoji is valid and that your server allows external emojis; ensure the bot can use external emojis.

• Panel message ID unknown: Use /reactionrole list or the dashboard’s Existing panels area to find configured message IDs.

• Select menu shows wrong options: Edit the panel with /reactionrole edit to reorder or correct option labels; if you swapped role IDs, fix them with the edit flow.

• Message reactions removed by moderation bots: Some moderation bots clean reactions; ensure any auto-moderation rules don’t remove legitimate panel reactions.

Quick cheat-sheet

/reactionrole create
/reactionrole add message_id:<id> emoji:<emoji> role:@Role
/reactionrole remove message_id:<id> emoji:<emoji>
/reactionrole delete message_id:<id>
/reactionrole list
/reactionrole edit message_id:<id>
/reactionrole panel name:<preset> channel:#channel
/reactionrole toggle message_id:<id> mode:enable|disable
/reactionrole setup