Reaction Roles

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/admin/reactionrole.ts
• src/handlers/reactionRoles.ts
• src/database/schemas/ReactionRoles.ts
• src/events/reaction/messageReactionAdd.ts
• src/commands/admin/settings/status.ts

The Reaction Roles system allows server administrators to configure messages where users can gain or lose roles by adding or removing a reaction. This feature provides a simple and interactive way for users to self-assign roles for server access, notifications, or personalization.

The system is composed of a command for setup, event handlers for user interactions, a database schema for persistence, and an in-memory cache for performance. Configuration is managed via the /reactionrole command, and the bot automatically handles role assignments when users react to the configured message.

Architecture Overview

The Reaction Roles feature is driven by four main components: the command, the event listener, the handler, and the database schema with its caching layer.

1. Command (/reactionrole): An admin-only slash command used to add or remove reaction role configurations on a specific message.
2. Event Listeners (messageReactionAdd, messageReactionRemove): These listeners trigger when a user adds or removes a reaction anywhere in a server.
3. Handler (reactionRoleHandler): Processes the reaction events, checks if the reaction corresponds to a configured reaction role, and assigns or removes the role from the user.
4. Database Schema & Cache (ReactionRoles): A Mongoose schema defines how reaction role configurations are stored in MongoDB. An in-memory cache (rrCache) is used to quickly retrieve configurations without constant database queries.

This diagram illustrates the high-level interaction between the components.

Database Schema

The configuration for reaction roles is stored in the reaction-roles collection in MongoDB. Each document represents a single message that has reaction roles configured on it.

Sources: src/database/schemas/ReactionRoles.ts:9-25

ER Diagram

This diagram shows the structure of the reaction-roles document.

Schema Fields

Field	Type	Required	Description
guild_id	String	Yes	The ID of the guild where the message exists.
channel_id	String	Yes	The ID of the channel where the message exists.
message_id	String	Yes	The ID of the message with reaction roles.
roles	Array	No	An array of objects, each mapping an emoji to a role.
roles.emote	String	Yes	The emoji used for the reaction (either a unicode character or a custom emoji ID).
roles.role_id	String	Yes	The ID of the role to be assigned.
created_at	Timestamp	Yes	Timestamp of when the document was created.

Sources: src/database/schemas/ReactionRoles.ts:11-21

Caching Mechanism

To optimize performance and reduce database load, reaction role configurations are stored in an in-memory Map called rrCache.

• Initialization: On bot startup, cacheReactionRoles is called to load all reaction role documents from the database into the rrCache. During this process, it validates that the guild and channel for each configuration still exist.
• Access: The getReactionRoles function retrieves configurations for a specific message directly from the cache using a key formatted as guildId|channelId|messageId.
• Updates: When an admin uses /reactionrole to add or remove a configuration, the corresponding functions (addReactionRole, removeReactionRole) update both the database and the rrCache to ensure data consistency.
• Eviction: The clearGuildReactionRoleCache function can be used to remove all cache entries for a specific guild.

Sources: src/database/schemas/ReactionRoles.ts:28-111

This flowchart shows the logic for retrieving a reaction role configuration.

Command Interface: /reactionrole

Administrators manage reaction roles using the /reactionrole slash command. It requires the ManageGuild permission.

Sources: src/commands/admin/reactionrole.ts:20-21

Command Options

Option	Type	Required	Description
action	String	Yes	The action to perform (add or remove).
channel	Channel	Yes	The text channel containing the message.
message_id	String	Yes	The ID of the message to configure.
emoji	String	For add	The emoji to use for the reaction.
role	Role	For add	The role to assign when a user reacts.

Sources: src/commands/admin/reactionrole.ts:26-62

System Status Display

The /settings status command includes a section that lists all currently active reaction role configurations in the server, providing a quick overview for administrators. It displays the message link, the channel, and the emoji-to-role mappings.

Sources: src/commands/admin/settings/status.ts:181-204

Data Flow

Configuration Flow (Adding a Reaction Role)

This sequence diagram shows the process when an admin adds a new reaction role.

User Interaction Flow (Getting a Role)

This sequence diagram illustrates what happens when a user adds a reaction to a configured message.

The flow for removing a reaction is nearly identical, but handleReactionRemove is called, which results in the bot removing the role from the user.

Sources: src/handlers/reactionRoles.ts:27-39

Validation and Permissions

Before a reaction role can be configured, the addRR function performs several checks:

• Bot Permissions: Verifies the bot has necessary permissions in the target channel (EmbedLinks, ReadMessageHistory, AddReactions, UseExternalEmojis, ManageMessages).
• Message Validity: Ensures the provided message_id is valid and the message can be fetched.
• Role Hierarchy: Checks that the bot's highest role is positioned above the role being assigned.
• Role Type: Prevents assignment of managed (bot) roles or the @everyone role.
• Emoji Validity: For custom emojis, it confirms the emoji belongs to the server. It also validates that the bot can use the emoji.

Sources: src/commands/admin/reactionrole.ts:103-142