Skip to main content
Volvox.Bot ships a full moderation toolkit. Every action creates a numbered case in the database, optionally DMs the target, and posts a log embed to your dedicated moderation channels.

​
Commands

Issue a warning to a server member. Requires the moderator role.
OptionRequiredDescription
userYesThe member to warn
reasonNoReason for the warning
severityNolow (default), medium, or high
Each warn creates both a mod case and a linked warning record with a severity-based point weight. After issuing the warning, escalation thresholds are checked automatically.
Remove a member from the server without banning them. Requires the admin role.
OptionRequiredDescription
userYesThe member to kick
reasonNoReason for the kick
Permanently ban a user. Works even if the user is not currently in the server. Requires the admin role.
OptionRequiredDescription
userYesThe user to ban
reasonNoReason for the ban
delete_messagesNoDays of messages to delete (0–7, default 0)
Ban a user for a fixed duration. The bot automatically unbans them when the timer expires. Requires the admin role.
OptionRequiredDescription
userYesThe user to ban
durationYesDuration string (e.g. 1h, 7d, 30m)
reasonNoReason for the ban
Ban and immediately unban a user to delete their recent messages without a permanent ban. Requires the admin role.
OptionRequiredDescription
userYesThe user to softban
reasonNoReason
Mute a member for a specified duration (up to 28 days). Requires the admin role.
OptionRequiredDescription
userYesThe member to time out
durationYesDuration string (e.g. 30m, 1h, 7d)
reasonNoReason
Remove an active timeout from a member early. Requires the admin role.
OptionRequiredDescription
userYesThe member to untimeout
reasonNoReason
Remove a ban. Requires the admin role.
OptionRequiredDescription
userYesThe user ID to unban
reasonNoReason
Bulk-delete messages from a channel. Requires the admin role.
OptionRequiredDescription
amountYesNumber of messages to delete (1–100)
userNoDelete only messages from this user
Prevent non-moderators from sending messages in a channel (/lock) or restore normal permissions (/unlock). Both require the admin role.
OptionRequiredDescription
reasonNoReason (logged)
Set a per-message cooldown on a channel. Requires the admin role.
OptionRequiredDescription
secondsYesSlowmode interval in seconds (0 to disable)

​
Warning system

Warnings are first-class records with severity, point weights, and automatic expiry.

​
Severity levels

SeverityDefault points
low1
medium2
high3
Point values are configurable: 
"moderation": {
  "warnings": {
    "severityPoints": {
      "low": 1,
      "medium": 2,
      "high": 3
    }
  }
}

​
Warning expiry

Set expiryDays to automatically deactivate old warnings. The expiry scheduler runs every 60 seconds. 
"moderation": {
  "warnings": {
    "expiryDays": 90
  }
}
Set expiryDays to 0 or omit it to make warnings permanent.

​
Escalation

When a warning threshold is reached, the bot automatically applies a configured action — no moderator intervention needed. 
"moderation": {
  "escalation": {
    "enabled": false,
    "thresholds": [
      {
        "warns": 3,
        "withinDays": 7,
        "action": "timeout",
        "duration": "1h"
      },
      {
        "warns": 5,
        "withinDays": 30,
        "action": "ban"
      }
    ]
  }
}
Escalation only counts active warnings (not expired). Each threshold is checked in order; the first match wins.

​
Protected roles

Protected members — server owner, admins, moderators, or any explicitly listed roles — cannot be moderated by bot commands. This prevents accidental self-moderation. 
"moderation": {
  "protectRoles": {
    "enabled": true,
    "includeServerOwner": true,
    "includeAdmins": true,
    "includeModerators": true,
    "roleIds": []
  }
}
Admins and moderators are resolved from permissions.adminRoleIds and permissions.moderatorRoleIds.

​
DM notifications

Before executing an action, the bot DMs the target member with a formatted embed explaining what happened and why. DM delivery is best-effort — if the user has DMs disabled, the action still proceeds. 
"moderation": {
  "dmNotifications": {
    "warn": true,
    "timeout": true,
    "kick": true,
    "ban": true
  }
}
Set any key to false to suppress DMs for that action type.

​
Mod log channels

Every moderation action posts a rich embed to a configured log channel. You can route different action types to different channels, or use a single default channel for everything. 
"moderation": {
  "logging": {
    "channels": {
      "default": null,
      "warns": null,
      "bans": null,
      "kicks": null,
      "timeouts": null,
      "purges": null,
      "locks": null
    }
  }
}
Set the channel IDs you want to use and leave the rest null. The default channel is used as a fallback when a specific channel is not set. Log embeds include the case number, target and moderator mentions, reason, and — for timed actions — the duration.

​
Case system

Every moderation action creates a numbered case scoped to your server. Case numbers are sequential and assigned with an advisory database lock to prevent duplicates under concurrent actions. Cases record:
  • Case number and action type
  • Target user ID and tag
  • Moderator user ID and tag
  • Reason
  • Duration (for timeouts and tempbans)
  • Expiry timestamp
  • ID of the log message (for future edits)
You can look up cases and full warning history via the /case and /history commands (admin only).

​
Full config reference

"moderation": {
  "enabled": true,
  "alertChannelId": "1438665401243275284",
  "autoDelete": false,
  "dmNotifications": {
    "warn": true,
    "timeout": true,
    "kick": true,
    "ban": true
  },
  "escalation": {
    "enabled": false,
    "thresholds": [
      { "warns": 3, "withinDays": 7, "action": "timeout", "duration": "1h" },
      { "warns": 5, "withinDays": 30, "action": "ban" }
    ]
  },
  "logging": {
    "channels": {
      "default": null,
      "warns": null,
      "bans": null,
      "kicks": null,
      "timeouts": null,
      "purges": null,
      "locks": null
    }
  },
  "protectRoles": {
    "enabled": true,
    "roleIds": [],
    "includeAdmins": true,
    "includeModerators": true,
    "includeServerOwner": true
  },
  "warnings": {
    "expiryDays": 90,
    "severityPoints": {
      "low": 1,
      "medium": 2,
      "high": 3
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us