Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/onesoft-sudo/sudobot/llms.txt

Use this file to discover all available pages before exploring further.

Reaction roles allow members to pick up Discord roles simply by reacting to a pinned or designated message with a specific emoji. When a member adds the reaction, SudoBot assigns the configured role or roles. When they remove the reaction, SudoBot removes those roles. The system supports rate limiting, per-entry permission and role requirements, user blacklists, permission level gating, and a “single” mode that enforces mutual exclusivity across all reaction roles on the same message.

​
Enabling the system

Reaction roles must be enabled in your guild config before any triggers can fire: 
{
  "reaction_roles": {
    "enabled": true,
    "ignore_bots": true,
    "ratelimiting": {
      "enabled": true,
      "timeframe": 7000,
      "max_attempts": 5,
      "block_duration": 10000
    }
  }
}
FieldTypeDefaultDescription
enabledbooleanfalseMaster switch for the entire reaction role system.
ignore_botsbooleantrueSkip reactions from bot accounts.
ratelimiting.enabledbooleantrueEnable per-user rate limiting on reactions.
ratelimiting.timeframeinteger (ms)7000Window within which max_attempts is counted.
ratelimiting.max_attemptsinteger5Maximum reactions allowed per user within the timeframe.
ratelimiting.block_durationinteger (ms)10000How long to block a user after they exceed the limit.

​
Creating a reaction role trigger

Use the createreactionrole command (aliases: crr, rr) to attach an emoji trigger to any message in your server. 
/createreactionrole link:<message-link> emoji:<emoji> roles:<role-mentions> [mode:SINGLE|MULTIPLE]
OptionRequiredDescription
linkYesA Discord message link (discord.com/channels/…). Must be from the current server.
emojiYesThe emoji that triggers the role assignment. Can be a Unicode emoji or a server custom emoji.
rolesYesSpace-separated role mentions or IDs. Maximum 7 roles per trigger.
modeNoMULTIPLE (default) allows accumulating many roles; SINGLE enforces mutual exclusivity on the message.
Example: 
/createreactionrole link:https://discord.com/channels/111/222/333 emoji:🎮 roles:@Gamers mode:MULTIPLE
After you run this command, SudoBot automatically reacts to the target message with the emoji so members can see what to click.
You must have the Manage Roles permission to run createreactionrole. SudoBot also needs Manage Roles to assign and remove roles on members.

​
Setting up reaction roles step by step

1

Enable reaction roles in your config

Add the reaction_roles block to your guild config and set enabled: true, then restart or reload SudoBot.
2

Post or identify the target message

Navigate to the channel where you want the reaction role picker. Post a new message (e.g., “React below to pick your roles!”) or use an existing one. Enable Developer Mode, then right-click the message and select Copy Message Link.
3

Run createreactionrole

Pass the copied link, the trigger emoji, and the role(s) to assign.
/createreactionrole link:https://discord.com/channels/123/456/789 emoji:🔔 roles:@Notifications
SudoBot confirms success and lists the role names that will be assigned.
4

Test the trigger

React to the target message with the configured emoji. Your account should receive the role within a second or two. Remove the reaction to lose the role.

​
Role assignment modes

Members can hold roles from multiple emoji triggers on the same message simultaneously. Each trigger acts independently.Use this when you offer opt-in categories (e.g., game ping roles, interest tags) and members should be able to pick several.

​
Permission gating per trigger

Beyond the global config, each individual reaction role entry can enforce additional requirements before assigning roles:
RequirementBehavior when not met
requiredRolesMember must hold all listed roles. Reaction is removed and no roles are assigned.
blacklistedUsersListed user IDs cannot use the trigger (administrators bypass this). Reaction is removed.
requiredPermissionsMember must hold all listed Discord permissions. Reaction is removed.
levelWhen using level-based permissions, member must meet or exceed the minimum level. Reaction is removed.
When any check fails, SudoBot silently removes the member’s reaction via the REST API so the UI stays clean.

​
Rate limiting

The rate limiter tracks how many reactions a user submits within the configured timeframe. If the count reaches max_attempts, the user is blocked for block_duration milliseconds. During that window, all their reaction events are silently ignored.
Rate limit state is held in memory. Restarting the bot resets all rate limit counters. If you experience abuse during a restart window, consider lowering max_attempts or extending block_duration.

Snippets

Create reusable canned text responses with access controls.

Welcomer

Greet new members with custom messages and a Say Hi button.

Build docs developers (and LLMs) love

Get started for freeTalk to us