Moderation

Configure moderation features including automod, punishments, and warnings

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,
                },
            }
        },
    },
}