Role Management

Powerful role management tools for individual members and bulk operations. Assign temporary roles, add/remove roles, and manage roles across your entire server.

Features

Temporary Roles

Assign roles to specific members with automatic expiration.

  • Duration format: 1M 3d 1h 8m (months, days, hours, minutes)
  • Range: 1 minute to 1000 days
  • Automatic removal every 5 minutes via background task
  • MongoDB TTL indexes for guaranteed expiration

Individual Role Management

Add or remove roles for specific members instantly.

  • Add roles to any member
  • Remove roles from any member
  • Validation to prevent duplicate operations
  • Permission checks for security

Bulk Role Operations

Manage roles for multiple members at once with smart filtering.

  • Target all bots, all humans, or all members
  • Add or remove mode selection
  • Whitelist/blacklist role filters
  • 2-second delay between assignments to prevent rate limiting

Smart Filtering

Advanced filters for precise bulk operations.

  • Whitelist: Only affect members with ANY of these roles
  • Blacklist: Skip members with ANY of these roles
  • Automatic skip if role already assigned/removed
  • Up to 25 roles per filter

Command

/role

Interactive dashboard for all role management operations.

Individual Role Management

  • Temporary Role: Assign a role with automatic expiration
    • Select member and role
    • Enter duration (e.g., 1M 3d 1h 8m)
    • Role auto-expires after specified time
  • Add Role: Add a role to a specific member
    • Select member and role
    • Instant assignment
    • Validates role isn't already assigned
  • Remove Role: Remove a role from a specific member
    • Select member and role
    • Instant removal
    • Validates member has the role

Bulk Role Management

  • All Bots: Manage roles for all bot accounts
    • Select add/remove mode
    • Choose target role
    • Optional whitelist/blacklist filters
    • Only affects bots
  • All Humans: Manage roles for all human members
    • Same options as "All Bots"
    • Excludes bot accounts
    • Great for server-wide role updates
  • All Members: Manage roles for everyone in the server
    • Affects both bots and humans
    • Use with caution
    • Whitelist/blacklist highly recommended

Setup Guide

1. Assign Temporary Roles

Run /role → Temporary Role. Select a member, choose a role, and enter duration like 7d or 1M 3d.

Example: Give trial access for 7 days that auto-expires.

2. Individual Role Operations

Use Add Role or Remove Role buttons to quickly manage roles for specific members without temporary expiration.

3. Bulk Assign Roles

Click "All Humans" → Add mode → Select target role → Optionally add whitelist roles → Execute. Great for event roles or announcements.

4. Use Filters Effectively

Use whitelist to target specific groups (e.g., "Only affect members with 'Verified' role") and blacklist to exclude groups (e.g., "Skip 'Staff' members").

How It Works

Temporary Roles

When a temporary role is assigned, the bot stores it in MongoDB with an expiration timestamp. A background task runs every 5 minutes to check for expired roles and removes them automatically. MongoDB TTL indexes ensure roles are cleaned up even if the bot is offline.

Bulk Operations

Bulk operations fetch all server members and filter them based on the selected criteria (bots/humans/all). Then, whitelist and blacklist filters are applied. Finally, the bot checks if each member already has (or doesn't have) the target role before proceeding with the operation. A 2-second delay is added between each role assignment to prevent Discord API rate limiting.

Rate Limiting Protection

The bot includes a bulk role limiter that prevents multiple bulk operations from running simultaneously in the same server. This protects against rate limits and ensures operations complete successfully.

Common Use Cases

Trial Access

Give new members trial access to premium channels for 7 days using temporary roles.

Event Roles

Use bulk operations to assign event roles to all humans, then remove after the event ends.

Timeout Alternative

Create a "Muted" role and assign it temporarily as an alternative to Discord's built-in timeout.

Bot Management

Use "All Bots" to quickly assign or remove a bot-specific role from all bot accounts.

Announcement Roles

Assign announcement roles to all verified members using whitelist filter, skipping staff with blacklist.

Role Cleanup

Remove old or deprecated roles from all members at once with bulk remove operations.

FAQ

What happens if I assign a temporary role manually and then assign it again through the bot?

The bot will create a new expiration entry for that role. The role will be removed when the latest expiration time is reached.

Can I cancel a temporary role before it expires?

Yes, simply remove the role manually using Discord's interface or the bot's Remove Role command. The expiration entry will be cleaned up automatically.

How do whitelist and blacklist filters interact?

Whitelist is applied first (members must have ANY of the whitelist roles), then blacklist is applied (members must have NONE of the blacklist roles). Both filters work together for precise targeting.

What if a bulk operation fails midway?

The bot processes members one by one with error handling. If one member fails, the operation continues with remaining members. A final count shows how many were successfully processed.