🎓Moderation Master Tutorial

A heavy breakdown on the Moderation Plugin (lots of scrolling here, check the sidebar!)

This configuration takes place in the /configuration/moderation.json file!

You might need Discord Developer Mode on to get ID's and such!

Key words:

Boolean: A true or false switch

String: An assortment of "text" or "numbers" like this

Numbers: Just numbers!

Array: Strings or Numbers["in", "a", "pattern", "like", "this"]

Welcome!

Here we'll go over the Moderation setup in its entirety, with brief (or not so brief!) explanations and descriptions on things.

I made sure to separate everything the best possible so that the sidebar has a quick reference to what you're looking for.

Feedback is welcome!

If you think something is missing, or needs a bit more work, then make sure to leave us a note at our support server!

---

Basic Configuration Tutorial

"punishment _whitelist"

This configuration option accepts one role id. Every user who owns either the configured role or one above in the Discord role hierarchy cannot get punished using any moderation commands. We suggest to set this configuration option to the lowest staff role ID on your servers so that all staff members are protected from moderation commands (String)

Default: '804354024048427009',

A String statement, this is the thing that prevents your moderators themselves from being punished by Athena. Anyone with this role or higher is immune from moderation actions.

You theoretically could leave it blank, but we don't recommend it. It could break things.

Example:

We have a Owner role with ID 11111, Senior Staff role at ID 22222, Staff role at 33333, and a member role at ID 44444

"punishment_whitelist": 33333 causes any roles including itself and higher to be immune from moderation actions, while keeping the member role vulnerable to moderation actions.

"lock_roles"

List of role ids who get their access to write denied in every channel once it has been locked using /lock (Array)

Default: [ "884573835205148692", "804354028419022888" ],

An Array statement, this controls what roles get their writing privileges revoked in the server when using /lock, with it functioning like a pseudo-mute role. With it being an Array, you can set up multiple roles to do the job simultaneously.

You could leave it blank and not have an issue typically, but we recommend being cautious. It can vary by plugin, and some plugins might require at least something entered in. If it breaks or stops working, just fill it in and you'll be okay.

Example:

We have a Owner role with ID 11111, Senior Staff role at ID 22222, Staff role at 33333, Member role at ID 44444, Locked role at 55555, and New Member Role at 66666.

"punishment_whitelist": 55555 causes the Locked role to be assigned as a write-denied role when using /lock, leaving the rest intact.

---

Global Punishments

Global Punishments are a new feature in Athena! This allows you to submit a ban across multiple servers when you attach a proof image, giving the ability to other server staff to ban them according to your proof! Without proof, bans are done just locally!

"send_data"

If set to true, all bans that include a valid proof image will be submitted to Iynx Development. This data is shared across all AthenaBot instances, allowing other customers to ban the user on their servers based on your proof. If no proof image is provided, the ban data is not submitted. (Boolean)

Default: true,

A simple Boolean statement, this lets you choose if you want to send ban information to the API regarding bans.

It has to be either true or false, so there's no leaving it blank!

Usage:

On false, the bans never send, meaning all bans with proof are just at local-level.

On true, the bans are sent to Iynx Development, meaning others globally can see the ban.

"receive"

If set to true, all global ban requests will be sent to a configured channel, including all important information such as name, reason, and proof. Your moderators can then decide whether they want to ban the user on your Discord server or not. (Boolean)

Default: true,

A simple Boolean statement, this lets you choose if you want to receive ban information from the API regarding bans.

It has to be either true or false, so there's no leaving it blank!

Usage:

On false, the bans are never received, meaning you won't get any bans from external sources in your server.

On true, the bans are received, and are posted in the appropriate set-up channel, allowing interaction from other server members.

---

Mute Role

Mute roles can be applied to people instead of relying on Discord's Timeout feature if you want! This can help deal with how Discord Timeouts affect people's usage of buttons, dropdowns, etc.

Role Based Mute Config Snippet

        // This option is used to configure how you would like the mute function to
        // work. If set to true a "mute" role will be applied instead of the user
        // being timeouted with Discord's built in feature. Applying a mute role
        // can be useful due to timeouted users no longer being able to use any
        // interaction buttons/dropdown menus. This means they wouldn't be able
        // to create a ticket to appeal their punishment.
        // Note: If you enable role based mutes you must create a mute role and
        // change their permission in the Discord channel settings so they cannot
        // write anymore. The bot does only apply the role nothing else!
        role_based_mute: {
            // Whether you would like to enable role based mutes (Boolean)
            enabled: false,
            // Mute role ID (String)
            role_id: "804354031388196894",
        },

Usage:

It has to be either true or false, so there's no leaving it blank!

On false, the role based mute system is disabled entirely.

On true, Athena will activate the role based mute, however, Athena will only apply the role, it does not configure the role to do it's job of muting people. That part is up to the user (you!) to configure in the roles/channels manually.

The role_id is what it says it is, the ID for the role that is being made into the mute role. Note, it is not an Array, it takes a single role only.

---

Auto Punishments

Another Athena feature, this allows Athena to automatically punish users based on how many warnings they have accumulated. There's complete freedom on how many warnings someone needs, what their automatic punishments may be, and if their punishments reset over time or not.

Punishment Format Snippet

            //  {
            //      violations: 3, 
            //      type: "MUTE",
            //      duration: "1d",
            //      reset: false,
            //  },

• Violations: represents the number of warnings the user must get in order for this punishment to be applied.

For example, if you want someone to be punished with a mute that lasts for a day after 3 warnings, you would configure it like this.

(This would mute someone after 3 violations, for 1 day, and not reset their violations.)

Violations Config Example

            //  {
            //      violations: 3, 
            //      type: "MUTE",
            //      duration: "1d",
            //      reset: false,
            //  },

• Type: represents the punishment type. It can be either MUTE, KICK, or BAN.

Let's say a user's been persistently breaking the rules, and they've had a handful of warnings already, and let's assume you wanted to permanently ban them after 5 warnings, you'd configure it like this.

(This would ban someone after 5 violations, for 1 day, but not reset their violations.)

Type Config Example

            //  {
            //      violations: 5, 
            //      type: "BAN",
            //      duration: "1d",
            //      reset: false,
            //  },

• Duration: represents the length of the punishment.

Let's say you have a user that has been banned prior, so they've kept their log of warnings in the database. If you wanted to mute them for even longer than the first time they got muted, you can easily change the duration.

(This would mute someone after 10 violations, for 7 days, but not reset their violations.)

Duration Config Example

            //  {
            //      violations: 10, 
            //      type: "MUTE",
            //      duration: "7d",
            //      reset: false,
            //  },

• Reset: represents whether after this punishment was applied the violation count should be reset to 0.

Let's assume you're super forgiving to people, and you had someone temp banned from your server for a week, but you also didn't want them to keep a record on themselves after rejoining, you can configure Athena to reset their violation count after a certain threshold.

(This would ban someone on the 15th violation, for 7 days, but also reset their violation counter.)

Reset Config Example

            //  {
            //      violations: 15, 
            //      type: "BAN",
            //      duration: "7d",
            //      reset: true,
            //  },

The best part is, you can make a sliding scale this way, AKA you can have multiple automatic punishments set up in a row simply by adjusting the config like so:

Multiple Auto Punishment Config Example

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

---

Punishment Auto DM

Now you don't have to exactly tell people you punished them, you can just let Athena take care of it for you! Athena can automatically send a DM to whoever it is got punished by it, with the punishment description, length, and type!

Punishment Notification Config Snippet

    // If set to true every time a member is being punished the member
    // will be dmed by the bot telling them that they have been punished,
    // how and the reason (Boolean)
    punishment_notification: true,

Usage:

It has to be either true or false, so there's no leaving it blank!

On false, Athena will not message users.

On true, Athena will message users automatically with punishment details.

---

Automod Basics

Automod is arguably the biggest thing to configure here! With multiple settings, there's a lot of things to customize here. I'll go over it as much as possible.

Enabling it

Pretty simple, this toggles whether it's on or off.

It has to be either true or false, so there's no leaving it blank!

On false, Automod will be off.

On true, Automod will be on.

Automod Enabled Config Snippet

        // Whether this module should be enabled (Boolean)
        enabled: true,

Role Whitelisting

This configures what roles should be immune to the Automod. It is hierarchical, meaning the role itself and higher are immune to Automod. It's an Array statement, so...

You theoretically could leave it blank, but we don't recommend it. It could break things.

Automod Role Whitelisting Config Snippet

        // Configuration option "role_whitelist" requires a role id.
        // If the message author owns the configured role or one above
        // in the Discord role hierarchy the message is whitelisted 
        // from any automod rules (String)
        role_whitelist: "884573835205148692",

Ticket Whitelisting

This configures whether tickets are ignored from Automod.

It has to be either true or false, so there's no leaving it blank!

On false, tickets will be subjected to Automod rules.

On true, tickets will be ignored by Automod.

Automod Ticket Whitelisting Config Snippet

        // If set to true all messages sent in tickets are whitelisted
        // from any automod rules (Boolean)
        whitelist_ticket_channels: true,

Channel Whitelisting

If you're not a fan of certain channels having Automod, don't worry, you can assign them with this section. This will effectively make Athena ignore them.

This is an Array and an optional feature, so you could leave this blank with just [ "" ] and you'll be okay.

Automod Channel Whitelisting Config Snippet

        // Configuration option "whitelisted_channels" requires a list
        // of channel ids. Every message that is being sent in one of
        // these channels is whitelisted from any automod rules (Array)
        whitelisted_channels: ["804354119523500082", "947577986939514881"],

Category Whitelisting

The more powerful form of Channel Whitelisting, Category Whitelisting excludes any channels inside that category!

Same as above, this is an Array and an optional feature, so you could also leave it blank the same way like the other one.

Automod Category Whitelisting Config Snippet

            // Configuration option "whitelisted_categories" requires a list
            // of category ids. Every message that is being sent in one of
            // the channels within these categories is whitelisted from any
            // automod rules (Array)
            whitelisted_categories: ["804354054829506590"],

---

Automod Rules

Here is where we get into the details that drives Automod and how it functions on a deeper level, things could get a bit complicated here, or maybe not!

Regex

Personally, regex is out of my depth, but there's lots of resources online to make rules for regex than I could ever explain in any degree here! But what I do know is that you can configure Athena to pick up on certain phrases or words or even links and IPs! There's multiple things to this category and we'll go over them a bit.

This is what the initial configuration looks like for a regex rule:

Automod Regex Config Snippet

            // {
            //      name: "",
            //      regex: "",
            //      warn: false,
            // },

Small breakdown:

• Name: Represents the name of the rule. Can be changed to whatever you want, because this is what reflects on the Automod log as the reason for the punishment.

• Regex: Represents what the Automod filter would be looking for. Basically, if you set a simple word as the regex, it would look for anything that matches that word, unless you went a little more in detail and set up wildcards, expressions, etc.

• Warn: Represents whether the Automod will warn someone for the message that was caught. This is a toggleable option, which means you're able to set it to true or false to warn or simply delete and log respectively.

For example: If you wanted to warn someone for saying the word potato, you'd set it up like this:

Automod Regex Config Example

         {
              name: "Random",
              regex: "potato",
              warn: true,
         },

Mentions

As simple as it can get, a spam mention warn system.

This is what the initial configuration looks like for this rule:

Automod Mentions Config Snippet

            custom_rules: {
                // The "mentions" filter deletes messages based on the amount
                // of mentions it includes.
                mentions: {
                    // Whether this automod rule should be enabled (Boolean)
                    enabled: true,
                    // "name" represents the name of the rule. It is a random name
                    // that will be used for warn reasons and in the automod delete
                    // message (String)
                    name: "Mention Filter",
                    // How many mentions are allowed per message (Number)
                    max_mentions: 3,
                    // Should the bot issue a warning if this automod rule
                    // has filtered a message (Boolean)
                    warn: true,
                },

Enabling it

Pretty simple, this toggles whether it's on or off.

It has to be either true or false, so there's no leaving it blank!

On false, Mention spam filtering will be off.

On true, Mention spam filtering will be on.

Small breakdown:

• Name: Represents the name of the rule. Can be changed to whatever you want, because this is what reflects on the Automod log as the reason for the punishment.

• Max Mentions: Represents how many mentions one person can do in a message before getting warned.

• Warn: Represents whether the Automod will warn someone for the message that was caught. This is a toggleable option, which means you're able to set it to true or false to warn or simply delete and log respectively.

For example: If you wanted to warn someone for sending 5 mentions, you'd set it up like this:

Automod Mentions Config Example

            mentions: {
                // Whether this automod rule should be enabled (Boolean)
                enabled: true,
                // "name" represents the name of the rule. It is a random name
                // that will be used for warn reasons and in the automod delete
                // message (String)
                name: "Mention Filter",
                // How many mentions are allowed per message (Number)
                max_mentions: 5,
                // Should the bot issue a warning if this automod rule
                // has filtered a message (Boolean)
                warn: true,
            },

Repeating Messages

Another simple section, this handles spam messages.

This is what the initial configuration looks like for this rule:

Automod Repeat Messages Config Snippet

            repeating_message: {
                // Whether this automod rule should be enabled (Boolean)
                enabled: true,
                // "name" represents the name of the rule. It is a random name
                // that will be used for warn reasons and in the automod delete
                // message (String)
                name: "Repeating Message Filter",
                // How many times can a user post the same message until the
                // automod takes action (Number)
                max_message_repeat: 4,
                // Should the bot issue a warning if this automod rule
                // has filtered a message (Boolean)
                warn: true,
            },

Enabling it

Pretty simple, this toggles whether it's on or off.

It has to be either true or false, so there's no leaving it blank!

On false, Repeat Message filtering will be off.

On true, Repeat Message filtering will be on.

Small breakdown:

• Name: Represents the name of the rule. Can be changed to whatever you want, because this is what reflects on the Automod log as the reason for the punishment.

• Max Message Repeat: Represents how many times a message can be repeated before being deleted and warn logged.

• Warn: Represents whether the Automod will warn someone for the message that was caught. This is a toggleable option, which means you're able to set it to true or false to warn or simply delete and log respectively.

For example: If you wanted to warn someone for sending 5 same messages in a row, you'd set it up like this:

Automod Repeat Messages Config Example

            repeating_message: {
                // Whether this automod rule should be enabled (Boolean)
                enabled: true,
                // "name" represents the name of the rule. It is a random name
                // that will be used for warn reasons and in the automod delete
                // message (String)
                name: "Repeating Message Filter",
                // How many times can a user post the same message until the
                // automod takes action (Number)
                max_message_repeat: 5,
                // Should the bot issue a warning if this automod rule
                // has filtered a message (Boolean)
                warn: true,
            },

Blacklisted Words

Final section! Another simple one thankfully! This just looks for words that you don't want said in your server.

This is what the initial configuration looks like for this rule:

Automod Blacklisted Words Config Snippet

            blacklisted_words: {
                // Whether this automod rule should be enabled (Boolean)
                enabled: true,
                // "name" represents the name of the rule. It is a random name
                // that will be used for warn reasons and in the automod delete
                // message (String)
                name: "Blacklisted Words Filter",
                // List of blacklisted words that should get deleted (Array)
                blacklisted_words: [''],
                // Should the bot issue a warning if this automod rule
                // has filtered a message (Boolean)
                warn: true,
            },

Enabling it

Pretty simple, this toggles whether it's on or off.

It has to be either true or false, so there's no leaving it blank!

On false, Blacklisted Words filtering will be off.

On true, Blacklisted Words filtering will be on.

Small breakdown:

• Name: Represents the name of the rule. Can be changed to whatever you want, because this is what reflects on the Automod log as the reason for the punishment.

• Blacklisted Words: Represents what words are blocked from being said in chat.

• Warn: Represents whether the Automod will warn someone for the message that was caught. This is a toggleable option, which means you're able to set it to true or false to warn or simply delete and log respectively.

For example: If you wanted to warn someone for saying 'stupid' in chat, you'd set it up like this:

Automod Blacklisted Words Config Example

            blacklisted_words: {
                // Whether this automod rule should be enabled (Boolean)
                enabled: true,
                // "name" represents the name of the rule. It is a random name
                // that will be used for warn reasons and in the automod delete
                // message (String)
                name: "Blacklisted Words Filter",
                // List of blacklisted words that should get deleted (Array)
                blacklisted_words: ['stupid'],
                // Should the bot issue a warning if this automod rule
                // has filtered a message (Boolean)
                warn: true,
            },

---

Congrats! 🎉

You're all done here! Now you can move onto other plugins and see how they work!