Moderation Bot

Features

• 7 moderation commands — warn, timeout, untimeout, ban, unban, kick, nickname
• Per-action permission system — configure allowed roles and immune roles for each action
• Cooldowns — per-user, per-command cooldown to prevent spam (0–86400 seconds)
• Appeal links — configurable appeal link sent to banned users via DM
• Full moderation logging — all actions logged with moderator, reason, and timestamp
• Log viewers — /modlogs for quick view, /raw-modlogs for downloadable export
• Discord-native config — everything managed through /config, no web dashboard needed

Getting Started

1. Invite the Bot — Add Moderation Bot to your server.
2. Run /config — Open the configuration panel (Administrator only).
3. Set Up Actions — For each action (ban, kick, timeout, warn, nickname), configure:
   • Allowed Roles — which roles can use this action
   • Immune Roles — which roles cannot be targeted
   • Cooldown — seconds between uses per user
   • Appeal Link — (ban only) sent to banned users via DM
4. Start Moderating — Use the commands below. All actions are logged automatically.

Actions are blocked by default until configured. You must set at least one allowed role per action via /config.

Moderation Commands

All commands are slash commands and work in servers only.

/ban

/ban <user> <reason>

Ban a user from the server. Works on members and non-members.

• DMs the user before banning (includes appeal link if configured)
• Respects immune roles and role hierarchy

/unban

/unban <user> <reason>

Unban a previously banned user. Uses the ban permission config (same allowed roles) but has a separate cooldown.

/kick

/kick <member> <reason>

Kick a member from the server. DMs the member before kicking.

/timeout

/timeout <member> <duration> <reason>

Timeout (mute) a member for a specified duration.

• Duration format: 12h, 3d 30m, 1d 6h 30m (supports s, m, h, d)
• Max duration: 28 days
• DMs the member after timing out

/untimeout

/untimeout <member> <reason>

Remove a timeout from a member. Uses the timeout permission config but has a separate cooldown. DMs the member after removing timeout.

/warn

/warn <member> <reason>

Issue a warning to a member. Cannot warn bots. DMs the member after warning.

/nickname

/nickname <member> <reason> [new_nickname]

Change or reset a member’s nickname. Leave new_nickname empty to reset to default.

Configuration

/config

Opens an interactive configuration panel (Administrator only) showing all 5 actions: ban, kick, timeout, warn, nickname.

For each action, you can see and edit:

• Allowed Roles — roles permitted to use the action (up to 25)
• Immune Roles — roles that cannot be targeted (up to 25)
• Cooldown — seconds between uses per user (0–86400, default: 60)
• Appeal Link — (ban only) URL sent in DM to banned users

Two buttons per action:

• Edit — opens a modal to update settings
• Reset — clears the action config (requires typing “confirm”)

Moderation Logs

All moderation actions are automatically logged with:

• Timestamp
• Moderator
• Action type
• Target user
• Reason

/modlogs

/modlogs <user>

View the latest 20 moderation actions for a user with relative timestamps. Requires any configured moderation role.

/raw-modlogs

/raw-modlogs <user>

Export all moderation logs for a user as a downloadable text file. Requires any configured moderation role. Response is ephemeral.

Limits

FAQ

Why can’t I use any moderation commands? Actions are blocked until configured. Run /config as an Administrator and set at least one allowed role for each action you want to use.

Do ban and unban share the same permission? Yes, they use the same allowed/immune roles config. But they have separate cooldowns.

Does the bot DM users before taking action? Yes, for ban, kick, timeout, untimeout, and warn. DM failures are silently handled — the action still proceeds.

What happens if the bot can’t manage a user’s role? The bot checks role hierarchy before acting. If the target’s highest role is equal to or above the bot’s, the action is refused with an error message.