Moderation

Introduction

The Moderation configuration file (moderation.json) controls punishment systems, automatic moderation rules, warning thresholds, and other safety features for your server.

Punishment Whitelist

Type: String

Role ID that cannot be punished by moderation commands.

punishment_whitelist: '804354024048427009'

Users with this role (or any role higher in the Discord role hierarchy) are protected from all moderation commands.

Recommendation: Set this to your lowest staff role so all staff members are protected from accidental punishment.

Lock Roles

Type: Array of Strings

List of role IDs that lose write access when /lock is used.

lock_roles: [
    "884573835205148692",
    "804354028419022888",
]

When you use /lock on a channel, these roles will have their send message permission removed.

Global Punishment

Share and receive ban information across all Athena Bot instances.

send_data

Type: Boolean

Submit your bans to the global punishment database.

global_punishment: {
    send_data: true,
}

When true: Bans with valid proof images are shared with other Athena Bot servers

When false: Your bans are not shared

Only bans with proof images are submitted.

receive

Type: Boolean

Receive global ban requests in a configured channel.

receive: true

When true: Global ban notifications are sent to your moderation channel

When false: You don't receive global ban requests

Moderators can review the information and decide whether to ban the user on your server.

Role-Based Mute

Use a mute role instead of Discord's timeout feature.

enabled

Type: Boolean

Enables role-based mutes instead of timeouts.

role_based_mute: {
    enabled: false,
}

Why use this: Discord timeouts prevent users from using buttons/dropdowns, which means they can't open tickets to appeal. Role-based mutes don't have this limitation.

role_id

Type: String

The mute role ID to apply when muting users.

role_id: "804354031388196894"

Important: You must manually configure the mute role's permissions in Discord channel settings. The bot only applies the role - it doesn't modify channel permissions.

Warning Punishments

Automatically punish users when they reach certain warning thresholds.

enabled

Type: Boolean

Enables automatic punishments based on warning count.

warn_punishments: {
    enabled: true,
}

punishments

Type: Array of Objects

Define punishments for specific warning thresholds.

punishments: [
    {
        violations: 1,
        type: "MUTE",
        duration: "3h",
        reset: false,
    },
    {
        violations: 3,
        type: "MUTE",
        duration: "1d",
        reset: false,
    },
    {
        violations: 5,
        type: "BAN",
        duration: 0,
        reset: true,
    },
]

violations - Number of warnings required

type - Punishment type: "MUTE", "KICK", or "BAN"

duration - Punishment length (e.g., "3h", "1d"), or 0 for permanent

reset - Whether to reset warning count to 0 after applying this punishment

Example Logic:

1 warning = 3-hour mute
3 warnings = 1-day mute
5 warnings = permanent ban and reset counter to 0

Punishment Notification

Type: Boolean

Send DM notifications to punished users.

punishment_notification: true

When true: Users receive a DM with punishment details, duration, and reason

When false: No DM is sent

Automod

Automatic message filtering and moderation system.

enabled

Type: Boolean

Enables or disables the entire automod system.

automod: {
    enabled: true,
}

role_whitelist

Type: String

Role ID that bypasses all automod rules.

role_whitelist: "884573835205148692"

Users with this role (or higher in the role hierarchy) are exempt from automod filtering.

whitelist_ticket_channels

Type: Boolean

Whether to exempt ticket channels from automod.

whitelist_ticket_channels: true

When true: Messages in ticket channels bypass automod

When false: Ticket channels are subject to automod rules

whitelisted_channels

Type: Array of Strings

Specific channel IDs exempt from automod.

whitelisted_channels: ["804354119523500082", "947577986939514881"]

whitelisted_categories

Type: Array of Strings

Category IDs where all channels are exempt from automod.

whitelisted_categories: ["804354054829506590"]

rules

Type: Array of Objects

Regex-based automod filters.

rules: [
    {
        name: "Invite Filter",
        regex: "(https?:\/\/)?(www\\.)?(discord\\.(gg|io|me|li)|discordapp\\.com\/invite)\/+[a-zA-Z0-9]{4,16}",
        whitelisted_text: [],
        warn: true,
    },
    {
        name: "IP Filter",
        regex: "(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d{1})\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d{1})",
        whitelisted_text: [],
        warn: true,
    },
]

name - Rule name (used in warn reasons and logs)

regex - Regular expression pattern to match

whitelisted_text - Array of strings/regex that bypass this specific rule

warn - Whether to issue a warning when this rule is triggered

Regex Resources:

Test patterns: https://regexr.com/
The config includes pre-configured filters for invites, IPs, Steam URLs, URL shorteners, Cyrillic spoofing, and Zalgo text

Custom Automod Rules

Special automod rules that require different detection methods than regex.

Mentions Filter

Delete messages with too many mentions.

custom_rules: {
    mentions: {
        enabled: true,
        rule_name: "Mention Filter",
        max_mentions: 3,
        warn: true,
    },
}

enabled - Whether this rule is active

rule_name - Name used in logs/warnings

max_mentions - Maximum mentions allowed per message

warn - Issue a warning when triggered

Repeating Message Filter

Delete duplicate consecutive messages.

repeating_message: {
    enabled: true,
    rule_name: "Repeating Message Filter",
    max_message_repeat: 4,
    warn: true,
}

max_message_repeat - How many times the same message can be sent before deletion

Blacklisted Words

Delete messages containing specific words.

blacklisted_words: {
    enabled: true,
    rule_name: "Restricted Words Filter",
    blacklisted_words: ["word1", "word2", "word3"],
    warn: true,
}

blacklisted_words - Array of words/phrases to filter

The default configuration includes a comprehensive list of inappropriate words.

Blacklisted Mentions

Prevent mentioning specific users.

blacklisted_mentions: {
    enabled: false,
    rule_name: "Blacklisted mentions",
    protected_users: ["123456789012345678"],
    warn: true,
}

protected_users - Array of user IDs that cannot be mentioned

Useful for protecting specific users from harassment.

Complete Configuration Example

Here's a production-ready moderation configuration:

{
    config: {
        punishment_whitelist: '804354024048427009',

        lock_roles: [
            "884573835205148692",
            "804354028419022888",
        ],

        global_punishment: {
            send_data: true,
            receive: true,
        },

        role_based_mute: {
            enabled: false,
            role_id: "804354031388196894",
        },

        warn_punishments: {
            enabled: true,
            punishments: [
                {
                    violations: 1,
                    type: "MUTE",
                    duration: "3h",
                    reset: false,
                },
                {
                    violations: 3,
                    type: "MUTE",
                    duration: "1d",
                    reset: false,
                },
                {
                    violations: 5,
                    type: "BAN",
                    duration: 0,
                    reset: true,
                },
            ]
        },

        punishment_notification: true,

        automod: {
            enabled: true,
            role_whitelist: "884573835205148692",
            whitelist_ticket_channels: true,
            whitelisted_channels: [],
            whitelisted_categories: [],

            rules: [
                {
                    name: "Invite Filter",
                    regex: "(https?:\/\/)?(www\\.)?(discord\\.(gg|io|me|li)|discordapp\\.com\/invite)\/+[a-zA-Z0-9]{4,16}",
                    whitelisted_text: [],
                    warn: true,
                },
                {
                    name: "IP Filter",
                    regex: "(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d{1})\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d{1})",
                    whitelisted_text: [],
                    warn: true,
                },
            ],

            custom_rules: {
                mentions: {
                    enabled: true,
                    rule_name: "Mention Filter",
                    max_mentions: 3,
                    warn: true,
                },
                repeating_message: {
                    enabled: true,
                    rule_name: "Repeating Message Filter",
                    max_message_repeat: 4,
                    warn: true,
                },
                blacklisted_words: {
                    enabled: true,
                    rule_name: "Restricted Words Filter",
                    blacklisted_words: [],
                    warn: true,
                },
                blacklisted_mentions: {
                    enabled: false,
                    rule_name: "Blacklisted mentions",
                    protected_users: [],
                    warn: true,
                },
            }
        },
    },
}

Moderation

On this page