Reaction Roles and Assignment
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot manages user roles through three primary mechanisms: automated assignment upon joining the server, self-service assignment via button interactions (reaction roles), and administrative bulk assignment using slash commands. These systems ensure that members receive necessary permissions immediately while allowing for granular notification preferences.
The role management system integrates with the Discord.js interaction framework, utilizing ephemeral replies to provide feedback to users without cluttering public channels.
Sources: AGENTS.md:14-16, README.md:21-25, src/handlers/interactionHandler.js:7-30
Automated Join Roles
Upon a new member joining the Discord server, the bot automatically assigns a set of predefined roles. This process is handled by the GuildMemberAdd event listener within the member handlers.
Logic and Configuration
The bot retrieves four mandatory role IDs from environment variables (AUTO_ROLE_ID_1 through AUTO_ROLE_ID_4). It also attempts to find a role named "user" within the guild's role cache. All identified roles are added to the member in a single API call to optimize performance.
Sources: src/handlers/memberHandlers.js:15-18, src/handlers/memberHandlers.js:23-55, src/config/env.js:1-10
The diagram shows the sequence of events from a member joining to the final role assignment and welcome message.
Sources: src/handlers/memberHandlers.js:16-55
Reaction Roles (Button Interactions)
Self-service role assignment is implemented using Discord Buttons rather than traditional emoji reactions. This allows users to toggle specific notification roles (e.g., "Site", "News", "Polls") on and off.
Interaction Flow
When a user clicks a button, the handleButtonInteraction function identifies the associated role name using a constant mapping. The toggleReactionRole function then checks the user's current roles:
- If the user already has the role, it is removed.
- If the user does not have the role, it is added.
Sources: src/interactions/buttonHandlers.js:13-24, src/interactions/buttonHandlers.js:125-177, src/config/constants.js:25-36
Configuration Mapping
The system uses a centralized configuration to map button customId strings to actual role names.
| Button ID | Label | Role Name |
|---|---|---|
role_site | Site | site |
role_monitor | Monitor | monitor |
role_polls | Polls | polls |
role_news | News | news |
role_notifs | Notifs | notifs |
Sources: src/config/constants.js:25-31
This sequence diagram illustrates the toggle logic used for button-based role assignments.
Sources: src/interactions/buttonHandlers.js:125-177
Administrative Role Assignment
For maintenance or server-wide updates, administrators can use the /put-member-role slash command. This command is specifically designed to reconcile roles by adding a specific auto-role to all members who are currently missing it.
Security and Execution
- Permissions: The command requires the user to possess the role defined by
PANEL_ADMIN_ROLE_ID. - Target Role: It specifically targets the role ID stored in
AUTO_ROLE_ID_4. - Filter: The command ignores bots and only processes human members who do not already have the target role.
- Feedback: The bot provides a summary of successful and failed assignments after completion.
Sources: src/interactions/slashHandlers.js:154-219, src/config/env.js:8
Command Implementation
// src/interactions/slashHandlers.js:183-186
const membersWithoutRole = guild.members.cache.filter(
member => !member.roles.cache.has(autoRoleId) && !member.user.bot
);
Summary of Role Constants and Env Vars
Role management relies heavily on environment variables validated at startup.
| Variable Name | Use Case |
|---|---|
AUTO_ROLE_ID_1 - 4 | Automatically assigned to new members. |
PANEL_ADMIN_ROLE_ID | Required to run /put-member-role. |
ADMIN_ROLE_ID | Required for admin-only commands like /wipe or /nuke. |
ALLOWED_COMMAND_ROLE_IDS | General permission to use bot slash commands. |
Sources: src/config/env.js:1-10, src/config/constants.js:1-23
TrackerBot's role system ensures high automation for community management while providing admins with the necessary tools for manual reconciliation and users with the ability to customize their notification experience.
Sources: README.md:21-25, src/handlers/memberHandlers.js:15-20