> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/configuration-files/moderation.md).

# Moderation

## <mark style="color:blue;">Introduction</mark>

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

***

## <mark style="color:blue;">Punishment Whitelist</mark>

**Type:** String

Role ID that cannot be punished by moderation commands.

```json
punishment_whitelist: '804354024048427009'
```

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

{% hint style="info" %}
**Recommendation:** Set this to your lowest staff role so all staff members are protected from accidental punishment.
{% endhint %}

***

## <mark style="color:blue;">Lock Roles</mark>

**Type:** Array of Strings

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

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

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

***

## <mark style="color:blue;">Global Punishment</mark>

Share and receive ban information across all Athena Bot instances.

### <mark style="color:yellow;">send\_data</mark>

**Type:** Boolean

Submit your bans to the global punishment database.

```json
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.

***

### <mark style="color:yellow;">receive</mark>

**Type:** Boolean

Receive global ban requests in a configured channel.

```json
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.

***

## <mark style="color:blue;">Role-Based Mute</mark>

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

### <mark style="color:yellow;">enabled</mark>

**Type:** Boolean

Enables role-based mutes instead of timeouts.

```json
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.

***

### <mark style="color:yellow;">role\_id</mark>

**Type:** String

The mute role ID to apply when muting users.

```json
role_id: "804354031388196894"
```

{% hint style="warning" %}
**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.
{% endhint %}

***

## <mark style="color:blue;">Warning Punishments</mark>

Automatically punish users when they reach certain warning thresholds.

### <mark style="color:yellow;">enabled</mark>

**Type:** Boolean

Enables automatic punishments based on warning count.

```json
warn_punishments: {
    enabled: true,
}
```

***

### <mark style="color:yellow;">punishments</mark>

**Type:** Array of Objects

Define punishments for specific warning thresholds.

```json
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

{% hint style="success" %}
**Example Logic:**

* 1 warning = 3-hour mute
* 3 warnings = 1-day mute
* 5 warnings = permanent ban and reset counter to 0
  {% endhint %}

***

## <mark style="color:blue;">Punishment Presets</mark>

Use punishment presets to make manual moderation commands faster and more consistent.

### <mark style="color:yellow;">punishment\_presets</mark>

**Type:** Object

Enable preset-based punishments and define a list of standard punishments for use in the moderation commands.

```json
punishment_presets: {
    enabled: false,
    presets: [
        {
            name: "Spamming",
            type: "MUTE",
            reason: "Spamming in chat",
            duration: "1h",
        },
        {
            name: "Harassment",
            type: "BAN",
            reason: "Harassing other members",
            duration: "1d",
        },
    ],
}
```

* `enabled` — Whether presets are enabled. When `true`, moderators can choose a preset in the `/warn`, `/mute`, `/kick`, and `/ban` preset subcommands.
* `presets` — List of preset punishments.
* `name` — The preset name shown in the command dropdown.
* `type` — The punishment type (`"WARN"`, `"MUTE"`, `"KICK"`, or `"BAN"`).
* `reason` — The reason that is logged when the punishment is applied.
* `duration` — How long the punishment lasts. Use `""` for a permanent punishment.

***

## <mark style="color:blue;">Punishment Notification</mark>

**Type:** Boolean

Send DM notifications to punished users.

```json
punishment_notification: true
```

**When `true`:** Users receive a DM with punishment details, duration, and reason\
**When `false`:** No DM is sent

***

## <mark style="color:blue;">Automod</mark>

Automatic message filtering and moderation system.

### <mark style="color:yellow;">enabled</mark>

**Type:** Boolean

Enables or disables the entire automod system.

```json
automod: {
    enabled: true,
}
```

***

### <mark style="color:yellow;">role\_whitelist</mark>

**Type:** String

Role ID that bypasses all automod rules.

```json
role_whitelist: "884573835205148692"
```

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

***

### <mark style="color:yellow;">whitelist\_ticket\_channels</mark>

**Type:** Boolean

Whether to exempt ticket channels from automod.

```json
whitelist_ticket_channels: true
```

**When `true`:** Messages in ticket channels bypass automod\
**When `false`:** Ticket channels are subject to automod rules

***

### <mark style="color:yellow;">whitelisted\_channels</mark>

**Type:** Array of Strings

Specific channel IDs exempt from automod.

```json
whitelisted_channels: ["804354119523500082", "947577986939514881"]
```

***

### <mark style="color:yellow;">whitelisted\_categories</mark>

**Type:** Array of Strings

Category IDs where all channels are exempt from automod.

```json
whitelisted_categories: ["804354054829506590"]
```

***

### <mark style="color:yellow;">rules</mark>

**Type:** Array of Objects

Regex-based automod filters.

```json
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

{% hint style="info" %}
**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
  {% endhint %}

***

## <mark style="color:blue;">Custom Automod Rules</mark>

Special automod rules that require different detection methods than regex.

### <mark style="color:yellow;">Mentions Filter</mark>

Delete messages with too many mentions.

```json
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

***

### <mark style="color:yellow;">Repeating Message Filter</mark>

Delete duplicate consecutive messages.

```json
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

***

### <mark style="color:yellow;">Blacklisted Words</mark>

Delete messages containing specific words.

```json
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.

***

### <mark style="color:yellow;">Blacklisted Mentions</mark>

Prevent mentioning specific users.

```json
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.

***

## <mark style="color:blue;">Complete Configuration Example</mark>

Here's a production-ready moderation configuration:

```json
{
    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_presets: {
            enabled: false,
            presets: [
                {
                    name: "Spamming",
                    type: "MUTE",
                    reason: "Spamming in chat",
                    duration: "1h",
                },
                {
                    name: "Harassment",
                    type: "BAN",
                    reason: "Harassing other members",
                    duration: "1d",
                },
            ],
        },

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