Skip to main content
Reaction roles let members get and remove server roles by reacting to a dedicated menu message. Mappings are stored in PostgreSQL so they survive bot restarts. The bot posts an embed listing all emoji-to-role mappings, and reacts to the message itself so members know which emojis to use.

​
How it works

1

Create a menu

Run /reactionrole create with a title and optional description. The bot posts an embed in the target channel and saves the menu to the database.
2

Add emoji mappings

Run /reactionrole add with the menu message ID, an emoji, and a role. The bot adds the mapping to the database, updates the embed, and reacts to the message with that emoji.
3

Members react

Members react to the menu message. The bot grants the corresponding role. Removing the reaction revokes the role.

​
Emoji support

Both Unicode emoji and custom server emoji are supported.
Emoji typeInput formatStored as
Unicode⭐⭐ (literal character)
Custom (static)<:name:id><:name:id>
Custom (animated)<a:name:id><a:name:id>
When you run /reactionrole add, pass the emoji exactly as it appears in Discord. For custom emoji, Discord renders them as <:name:id> in slash command inputs.
The bot must be a member of the server that owns a custom emoji to react with it. If you use an emoji from another server, reactions may fail silently.

​
Commands

Posts a new reaction-role menu embed in a channel.
OptionRequiredDescription
titleYesTitle shown on the embed
channelNoChannel to post in (defaults to current channel)
descriptionNoOptional text shown above the role list
After creating, the bot replies with the new message ID. Copy it — you need it for /reactionrole add.Requires Manage Roles permission.
Adds an emoji-to-role mapping to an existing menu.
OptionRequiredDescription
message_idYesID of the menu message
emojiYesEmoji to map
roleYesRole to grant
The bot validates that:
  • The menu message exists in the database
  • The menu belongs to this server
  • The bot’s role is above the target role in the hierarchy
  • Your role is above the target role in the hierarchy
If a mapping for that emoji already exists, it is replaced.
Removes an emoji mapping from a menu.
OptionRequiredDescription
message_idYesID of the menu message
emojiYesEmoji mapping to remove
The bot removes the mapping from the database, refreshes the embed, and clears its own reaction from the message.
Deletes an entire reaction-role menu. All emoji mappings are deleted (cascaded from the database). The bot also attempts to delete the Discord message.
OptionRequiredDescription
message_idYesID of the menu message
Lists all reaction-role menus in the server. Shows the menu title, channel, and message ID for each one.No options required.

​
Role menu templates

Role menu templates let you define a set of role options once and reuse them across guilds or re-apply them after changes. Templates are managed with the /rolemenu template command group.

​
Template commands

Lists all available templates — built-in and custom — grouped by category. Shows whether each template is built-in, custom, or shared with other guilds.
Shows the full details of a template: name, description, category, type, sharing status, and all configured options with their role IDs.
OptionRequiredDescription
nameYesTemplate name
Applies a template to the guild’s welcome.roleMenu configuration. Built-in templates have no role IDs — you must assign them in the config editor after applying.
OptionRequiredDescription
nameYesTemplate name
mergeNoMerge with existing options instead of replacing (default: replace)
After applying, run /welcome setup to post the updated role menu.
Creates a custom template for this guild.
OptionRequiredDescription
nameYesTemplate name (unique per guild)
optionsYesJSON array of role options
descriptionNoShort description
categoryNoCategory label (e.g. colors, pronouns, notifications)
The options value must be a valid JSON array:
[{"label": "Frontend", "description": "I build UIs", "roleId": "111222333444555666"}]
Each option requires at minimum a label. Options with an empty roleId are filtered out when the template is applied.
Deletes a custom template owned by this guild. Built-in templates cannot be deleted.
OptionRequiredDescription
nameYesTemplate name
Toggles whether a guild-owned custom template is visible to other guilds.
OptionRequiredDescription
nameYesTemplate name
enabledYestrue to share, false to make private
Reaction role menus require the Manage Roles permission. The bot’s highest role must be positioned above every role it assigns in Server Settings → Roles.

​
Database schema

Menus and entries are stored in two PostgreSQL tables:
  • reaction_role_menus — one row per menu (guild, channel, message, title, description)
  • reaction_role_entries — one row per emoji-to-role mapping, foreign-keyed to reaction_role_menus
Deleting a menu cascades to its entries. If the bot is restarted, all existing menus and mappings are restored from the database automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us