Self-Assign Roles

Pixl supports two methods for self-assignable roles: Reaction Roles and Button Roles.

Button Roles

Button roles use Discord buttons for a cleaner, more reliable experience.

Create a Button Role Menu

1. Create the menu:

   /buttonrole create channel:#roles title:"Pick Your Roles" description:"Click a button to toggle a role"

2. Add buttons:

   /buttonrole add message_id:123456789 label:"Announcements" role:@Announcements style:primary
   /buttonrole add message_id:123456789 label:"Events" role:@Events style:success emoji:🎉

3. Members click buttons to toggle roles.

Button Styles

Style	Color	Use Case
primary	Blue	Default choice
secondary	Gray	Less prominent
success	Green	Positive actions
danger	Red	Warnings, removals

Managing Button Menus

/buttonrole list                          # List all menus
/buttonrole remove <message_id> <label>   # Remove a button
/buttonrole delete <message_id>           # Delete entire menu

---

Reaction Roles

Reaction roles use emoji reactions on existing messages.

Add a Reaction Role

/reactionrole add message_id:123456789 emoji:🔔 role:@Notifications

The bot will:

1. Add the reaction to the message
2. Watch for users reacting
3. Assign/remove roles based on reactions

Managing Reaction Roles

/reactionrole list                              # List all reaction roles
/reactionrole list message_id:123456789         # List for specific message
/reactionrole remove message_id:123456789 emoji:🔔   # Remove a reaction role

---

Role Types

Both button and reaction roles support different behaviors:

Type	Behavior
normal	Toggle on/off (default)
unique	Only one role from a group
verify	One-time add, cannot remove
drop	One-time remove, cannot add

Unique Roles (Groups)

Use unique roles when users should only have one option from a set (e.g., color roles):

/buttonrole add message_id:123 label:"Red" role:@Red type:unique group:colors
/buttonrole add message_id:123 label:"Blue" role:@Blue type:unique group:colors
/buttonrole add message_id:123 label:"Green" role:@Green type:unique group:colors

When a user picks “Blue”, their “Red” role is automatically removed.

Verify Roles

Use verify roles for one-time verification:

/buttonrole add message_id:123 label:"I agree to the rules" role:@Verified type:verify

Once clicked, the user gets the role and cannot remove it themselves.

---

Best Practices

1. Use buttons for new setups - They’re more reliable and look cleaner
2. Group related roles - Use the group option for mutually exclusive choices
3. Check role hierarchy - Bot’s role must be above roles it assigns
4. Avoid managed roles - Bot/integration roles cannot be assigned
5. Limit options - Max 25 buttons per menu (5 rows × 5 buttons)

Troubleshooting

”I cannot manage this role”

The bot’s highest role must be above the role you’re trying to assign. Go to Server Settings > Roles and drag the Pixl role higher.

Reactions not working

1. Check if the bot has Add Reactions permission
2. Verify the emoji is valid (server emojis must be from your server)
3. Run /reactionrole list to confirm the configuration exists

Buttons not responding

1. Check if the menu still exists: /buttonrole list
2. Verify the bot has Send Messages permission in the channel
3. Ensure the role still exists and isn’t managed