ZMN Bot Logo
    Documentation

    ZMN Bot Documentation

    Setup guides and configuration reference for every ZMN module — security, moderation, roles, leveling, and access control.

    Quick Navigation

    Basics
    Modules

    Moderation

    Complete moderation system with commands, auto-mod, case management, and auto-revert

    Overview

    The Moderation module provides a comprehensive toolkit for server moderation. It combines slash commands for manual moderation, an auto-mod engine for automated message filtering, a case management system for tracking all actions, and an auto-revert scheduler for temporary punishments.

    What's Included

    • • 19 Moderation Commands — ban, kick, mute, timeout, warn, and more
    • • 8 Auto-Mod Detectors — bad words, spam, invites, caps, links, and more
    • • Case Management — track every action with auto-incrementing case IDs
    • • Auto-Revert Scheduler — temporary bans, mutes, locks automatically revert
    • • Escalation System — automatic punishment escalation based on warn count
    • • Discord AutoMod Sync — syncs rules to Discord's native AutoMod

    Moderation Commands

    All moderation commands use a permission guard system. Users need either the configured allowedRoles, allowedUsers, or Discord permissions to use them.

    User Punishment

    /banSlash Command

    Ban a user from the server

    Usage: /ban <user> [reason] [duration]
    Auto-reverts if revertAfter is configured
    /unbanSlash Command

    Unban a previously banned user

    Usage: /unban <user_id> [reason]
    /kickSlash Command

    Kick a user from the server

    Usage: /kick <user> [reason]
    /muteSlash Command

    Mute a user (auto-creates Muted role)

    Usage: /mute <user> [reason] [duration]
    Auto-revert scheduled when duration is provided
    /unmuteSlash Command

    Remove mute from a user

    Usage: /unmute <user> [reason]
    /timeoutSlash Command

    Discord native timeout (max 28 days)

    Usage: /timeout <user> [reason] [duration]
    Discord native timeout (max 28 days)
    /untimeoutSlash Command

    Remove timeout from a user

    Usage: /untimeout <user> [reason]
    /warnSlash Command

    Issue a warning (triggers escalation check)

    Usage: /warn <user> [reason]
    /unwarnSlash Command

    Remove a warning from a user

    Usage: /unwarn <user> [reason]

    Channel Management

    /lockSlash Command

    Lock a channel preventing messages

    Usage: /lock [channel] [reason] [duration]
    Auto-revert scheduled when duration is provided
    /unlockSlash Command

    Unlock a previously locked channel

    Usage: /unlock [channel] [reason]
    /slowmodeSlash Command

    Set slowmode delay in a channel

    Usage: /slowmode <seconds> [channel] [duration]
    Auto-revert scheduled when duration is provided
    /clearSlash Command

    Bulk delete messages in a channel

    Usage: /clear <amount> [user] [channel] [reason]

    Voice Moderation

    /vmuteSlash Command

    Mute a user in voice channels

    Usage: /vmute <user> [reason] [duration]
    Auto-revert scheduled when duration is provided
    /vunmuteSlash Command

    Remove voice mute from a user

    Usage: /vunmute <user> [reason]
    /vkickSlash Command

    Disconnect a user from their voice channel

    Usage: /vkick <user> [reason]
    /moveSlash Command

    Move a user between voice channels

    Usage: /move <user> <channel> [reason]

    User Management

    /setnickSlash Command

    Change a user's nickname

    Usage: /setnick <user> [nickname]
    Leave nickname empty to reset
    /caseSlash Command

    View case summary or manage case status

    Usage: /case <user> [action]

    Auto-Mod Engine

    The auto-mod engine runs on every message sent in your server. It uses 8 configurable detectors to identify rule violations and automatically enforce actions. Only the first matching detector triggers per message to avoid double-punishment.

    Bad Words

    Matches message content against a custom word list and/or the built-in default list of ~50 profanity/slur words

    useDefaultListcustomWordscaseInsensitivematchWholeWord
    Repeated Text

    Detects repeated characters, words, lines, and excessive emoji usage

    maxCharRepeatsmaxWordRepeatsmaxLineRepeatsemojiLimit
    Discord Invites

    Detects Discord invite links with options to allow own guild and specific invite codes

    allowOwnGuildallowedInviteCodes
    External Links

    Domain blocklist/allowlist with URL shortener blocking and media embed options

    modedomainsblockShortenersallowMediaEmbeds
    Excessive Caps

    Detects messages with excessive capitalization based on percentage threshold

    percentThresholdminLengthminWordCount
    Excessive Spoilers

    Detects too many spoiler tags or excessive spoiler content length

    maxSpoilersmaxSpoilerChars
    Mass Mentions

    Detects mass user and role mentions, with option to ban @everyone

    maxUserMentionsmaxRoleMentionscountDuplicatesOncebanEveryoneMention
    Anti-Spam

    Rate-based spam detection for messages, duplicates, links, attachments, and emoji

    messagesPerWindowwindowSecondsduplicateThresholdlinkSpamThresholdattachmentSpamThresholdemojiSpamThreshold
    Each detector can be individually enabled/disabled and configured with its own action, log channel, and disabled channels/roles exemptions.

    Default Blocked Words

    The Bad Words detector includes a built-in list of approximately 50 English profanity and slur words. This list is intentionally conservative — it targets the most universally unwanted words while minimizing false positives.

    Common Profanityfuck, shit, asshole, bitch, dick, ...
    Hate Speech / Slursnigger, faggot, retard, chink, ...
    Sexual Contentporn, hentai, nude, cock, ...
    Insults / Leet-Speakwhore, cunt, stfu, wtf, ...

    Use Default List

    toggle

    Enable the built-in blocked words list (enabled by default)

    Custom Words

    text[]

    Add your own words to supplement or replace the default list. Press Enter after each word.

    Case Insensitive

    toggle

    Match words regardless of capitalization (enabled by default)

    Match Whole Word

    toggle

    Only match complete words using word boundaries (disabled by default — substring matching is used)

    The default list is stored in defaultBlockedWords.js and can be extended server-by-server via the Custom Words field in the dashboard. Servers that need stricter filtering should add entries there rather than modifying the bot source.

    Duration Format

    Duration options in moderation commands accept a simple shorthand format. Combine units for exact durations.

    Duration Units

    sSeconds30s = 30s
    mMinutes10m = 600s
    hHours1h = 3600s
    dDays7d = 604800s

    Examples

    10m10m — 10 minutes
    1h1h — 1 hour
    30s30s — 30 seconds
    1d12h1d12h — 1 day and 12 hours
    7d7d — 7 days
    2h30m2h30m — 2 hours and 30 minutes
    You can combine multiple units in any order. If no unit is specified, seconds are assumed. The maximum duration for Discord timeout is 28 days.

    Supported Auto-Revert Actions

    When a duration is provided, the action is automatically reverted when the time expires. For example, /mute @user 10m will unmute the user after 10 minutes.

    ban → unbanauto-revert
    mute → unmuteauto-revert
    vmute → vunmuteauto-revert
    lock → unlockauto-revert
    slowmode → resetauto-revert
    timeout — Discord nativeDiscord native
    When a moderator provides a duration option, auto-revert is always scheduled regardless of the autoRevert setting. The setting only controls whether the default duration is used when no duration is specified.

    Auto-Revert & Scheduler

    Duration-based moderation actions automatically schedule a revert. When a moderator specifies a duration (e.g., /mute @user 10m), the bot schedules an auto-unmute for 10 minutes later.

    1Command with Duration

    Moderator runs a command with a duration option (e.g., /mute @user 10m). The action is applied immediately.

    2Schedule Created

    A ScheduledAction document is stored in MongoDB with the revert action (e.g., unmute) and fireAt timestamp.

    3Periodic Sweep

    The scheduler service runs a periodic sweep, finding all actions where fireAt has passed. It uses broadcastEval to execute on the correct shard.

    4Auto-Revert Executed

    The revert action runs (e.g., unmute), a companion "system" case is created, and the ScheduledAction document is removed.

    Escalation System

    The escalation system automatically escalates punishments based on a user's warn count. When a warn is issued, the system checks the user's total active warns against configured rules.

    Example Escalation Rules

    3 warns→ Mute (1h)
    5 warns→ Kick
    7 warns→ Ban

    Escalation Rules

    rules[]

    Define warn count thresholds and corresponding automatic actions. Each rule specifies a warn count, action type, and optional duration.

    Case Management

    Every moderation and security action creates a case with an auto-incrementing case ID. Cases track the full lifecycle of an action and can be managed from both Discord and the dashboard.

    Case Fields

    Case IDAuto-incrementing integer
    Typeban, mute, kick, warn, timeout, ...
    Sourcecommand, automod, security, escalation, system
    Statusopen → reviewing → resolved → closed
    Activetrue/false (action still in effect)

    Status Lifecycle

    Open→Reviewing→Resolved→Closed

    Case Managers

    Case managers can change case status from both the dashboard and the /case command. Permission is checked across both moderation and security modules:

    • Moderation case managers: moderation.master.caseManagerRoles + caseManagerUsers
    • Security case managers: security.caseManagerRoles + caseManagerUsers
    • Guild owner: Always has case management access

    Configuration

    Master Settings

    Whitelist Roles

    roles

    Roles exempt from all moderation actions

    Whitelist Users

    users

    Users exempt from all moderation actions

    Alert Roles

    roles

    Roles that receive DM notifications for moderation events

    Alert Users

    users

    Users that receive DM notifications for moderation events

    Case Manager Roles

    roles

    Roles that can manage case status

    Case Manager Users

    users

    Users that can manage case status

    Admin Roles

    roles

    Roles treated as administrators for hierarchy checks

    Moderator Roles

    roles

    Roles treated as moderators for permission checks

    Per-Command Settings

    Each of the 19 moderation commands can be individually configured:

    Enabled

    toggle

    Turn this command/detector on or off

    Require Reason

    toggle

    Force moderators to provide a reason

    Log Channel

    channel

    Channel for this command's log embeds

    Allowed Roles

    roles

    Roles that can use this command (in addition to Discord permissions)

    Allowed Users

    users

    Users that can use this command

    Disabled Channels

    channels

    Channels where this command/detector cannot be used

    Disabled Roles

    roles

    Roles that cannot be targeted by this command / Roles exempt from this detector

    Default Duration

    number

    Default duration in seconds (for mute, timeout, vmute)

    Auto-Revert

    toggle

    Automatically revert after default duration when no duration specified

    Revert After

    number

    Seconds after which to auto-revert (when autoRevert is enabled)

    Per-Event Settings (Auto-Mod)

    Each of the 8 auto-mod detectors can be individually configured:

    Enabled

    toggle

    Turn this command/detector on or off

    Action

    select

    What happens when triggered: delete, warn, mute, timeout, kick, or ban

    Duration

    number

    Duration for the action (e.g., mute for 600 seconds)

    Log Channel

    channel

    Channel for this command's log embeds

    Disabled Channels

    channels

    Channels where this command/detector cannot be used

    Disabled Roles

    roles

    Roles that cannot be targeted by this command / Roles exempt from this detector

    DM on Action

    DM on Action

    toggle

    Send a DM to the target user when a moderation action is applied

    DM Message

    text

    Custom message template. Placeholders: {action}, {server}, {reason}

    template
    You were {action} in {server} for: {reason}

    Log Embeds

    All moderation commands send rich embeds to the configured log channel. These embeds are standardized with consistent formatting for easy scanning:

    • • Emoji + Action Title: 🔨 Ban, 👢 Kick, 🔇 Mute, ⚠️ Warn, 🔒 Channel Locked, etc.
    • • Color Coding: Red (ban), orange-red (kick), amber (mute/timeout), green (un-commands), yellow (warn), grey (channel ops), blue (setnick)
    • • Thumbnail: Target user avatar (or moderator avatar for channel actions)
    • • Fields: Target, Moderator, Duration, Auto-Revert, Reason, Channel
    • • Footer: GuildName • Case #ID
    • • Timestamp: When the action was taken

    Ephemeral Replies

    Moderators receive a compact embed as an ephemeral reply confirming the action. These use a simplified format: emoji + action name + target, with the case ID in the footer.

    Discord AutoMod Sync

    ZMN Bot can sync your moderation event settings to Discord's native AutoMod rules. This provides an additional layer of protection that works even if the bot is temporarily offline.

    Synced Rules

    • • Bad Words → Discord KEYWORD filter (uses customWords only)
    • • Discord Invites → Discord KEYWORD filter (regex pattern)
    • • Mass Mentions → Discord MENTION_SPAM filter
    • • Excessive Caps → Discord KEYWORD filter (regex pattern)
    Synced rules are prefixed with ZMN: in Discord's AutoMod settings. The bot cleans up old ZMN-managed rules before creating new ones on each sync.

    Best Practices

    ✓ Recommended Setup

    • • Start with auto-mod detectors set to delete action before escalating to warn/mute
    • • Use requireReason: true for ban, kick, and mute commands
    • • Configure case manager roles so your mod team can manage cases from the dashboard
    • • Set up escalation rules to automatically handle repeat offenders
    • • Use disabledChannels for bot commands channels where spam detection isn't needed
    • • Enable DM on Action so users know why they were punished
    • • Use duration options for temporary actions — auto-revert ensures nothing is forgotten

    ✗ Common Mistakes

    • • Setting auto-mod action to ban for first offenses (too aggressive)
    • • Not configuring whitelist roles (bot/moderator messages get flagged)
    • • Forgetting to set a log channel (no visibility into actions)
    • • Using permanent mutes/bans without duration when temporary action is intended
    • • Not testing escalation rules before enabling (can lead to unexpected bans)
    • • Adding too many custom words to badWords without matchWholeWord (causes false positives)
    Bot Hierarchy Requirement: The bot's role must be positioned higher than the Muted role and any roles it needs to manage. For ban/kick commands, the bot needs the corresponding Discord permissions. For the mute command, the bot auto-creates a Muted role and configures channel permission overwrites.