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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iynxdev.com/configuration-files/moderation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.