Moderation Features Reference

A detailed reference for the advanced features in the Moderation cog, including the mute system, role persistence, duration formats, modlog sharing, and preset reasons.

Mute System

The mute system assigns a configurable “muted” role to silence users. Unlike Discord’s native timeout, mutes are tracked in the database and survive bot restarts.

How a mute works:

  1. /mute applies the configured mute role to the user
  2. A database record is created with the expiry time
  3. The user receives a DM with the reason and duration (if DMs are open)
  4. A modlog entry is created with an incrementing case number
  5. A background task automatically removes the mute role when it expires
  6. If the user leaves and rejoins while muted, the mute role is reapplied automatically

Prerequisites:

  • A mute role must exist in your server
  • The mute role must be positioned below the bot’s role in Server Settings - Roles
  • The mute role must be set in /moderation config (Muted Role setting)
  • The mute role should deny Send Messages, Add Reactions, and Speak in your channels

Role Persist System

Role persist assigns any role to a user with optional expiry, tracked in the database. Useful for probation periods, temporary access, or any role that should survive server leaves.

How role persist works:

  1. /rolepersist apply assigns the specified role with an optional duration
  2. The assignment is stored in the database
  3. If the user leaves and rejoins, the role is automatically reapplied
  4. When the duration expires, the role is removed by a background task
  5. Removing a persist entry stops future reapplication but does not strip the role from the user unless done manually

Common uses:

  • Temporary trial or probation roles with automatic expiry
  • Persistent access roles that should survive leaves/rejoins
  • Any timed role assignment that outlasts the session

Duration Format

All commands that accept a duration use the following format:

Format Meaning Example
Ns N seconds 30s
Nm N minutes 30m
Nh N hours 2h
Nd N days 7d
Nw N weeks 2w
0 Permanent (never expires) 0

Auto-Expiry

A background task runs every minute and handles automatic cleanup:

  • Finds all active mutes and role persists that have passed their expiry time
  • Removes the relevant roles from the user
  • Marks the database record as inactive
  • Logs each automatic removal

On bot startup, the task also processes any entries that expired during downtime, so no expirations are missed.

Modlog Sharing

Modlog sharing lets servers view each other’s moderation history. Useful for multi-server communities where you want cross-server visibility of bans, mutes, and warns.

Both servers must configure their side for sharing to be active.

Share your modlogs with another server:

/moderation share_modlogs_with <server_id>
/moderation unshare_modlogs_with <server_id>

Accept modlogs shared from another server:

/moderation accept_modlogs_from <server_id>
/moderation stop_accepting_from <server_id>

View active sharing configuration:

/moderation list_sharing

Once set up, /modlogs and /whois will show moderation history from all servers you are accepting modlogs from.

Preset Reasons

Preset reasons let moderators save commonly used reasons that appear as autocomplete suggestions in any moderation command’s reason field.

Command Description
/moderation preset add <name> <reason> Save a preset reason
/moderation preset delete <name> Remove a preset reason
/moderation preset list View all saved preset reasons

Presets are server-scoped. When issuing a /ban, /mute, /warn, or other action, saved presets appear as autocomplete options in the reason field.

Permission Model

Many moderation commands are gated by a combination of Discord permissions and configurable role lists. All settings are configured via /moderation config.

Feature Default Requirement Configurable Setting
Ban / Unban Ban Members ban_enabled toggle
Kick Kick Members kick_enabled toggle
Mute / Unmute Manage Roles mute_allowed_roles
Warn / Editwarn Manage Messages warn_allowed_roles
Role Persist Manage Roles rolepersist_allowed_roles
Comped Manage Roles comped_enabled toggle
Configuration Administrator -

Punishment-Protected Roles

Users holding any role listed in punishment_protected_roles cannot be targeted by any moderation action - warn, mute, ban, kick, or comped. Configure via /moderation config.