RegexBot/docs/automod.md

AutoMod

AutoMod is a component that takes inspiration from Reddit's Automoderator. It was the original feature of RegexBot. It allows the operator to define one or more rules based on regular expression (regex) patterns. When a particular rule is matched, the bot executes the appropriate response.

AutoMod is set up by defining rules within a JSON object named automod within a server definition. Rules are defined by means of name/value pairs, with the name serving as its label.

Sample within a server definition:

"automod": {
    "Delete bilingual pirates": {
        "regex": [ "pira(te|cy)", "pirat(a|ería)", ],
        "response": [
            "delete"
            "report #0000000::mod-queue"
        ]
    },
    "Selective trigger": {
        "regex": "secret",
        "response: "say #_ Don't say the s word, @_!",
        whitelist: { "channels": [ "#dont-say-secret" ] }
    }
}

Rule structure

The following is a list of accepted members within an AutoMod rule:

• regex (string or string array) - Required. Regular expression pattern(s) that trigger the defined rule.
• response (string or string array) - Required. Response, or list of responses to execute.
  • See the section below for more information on defining responses.
• whitelist (entity list) - Entities to which the rule exclusively applies to.¹
• blacklist (entity list) - Entities to which the rule does not apply to.¹
• exempt (entity list) - Entities which are exempt from whitelist or blacklist rules.²
  • For example: It would allow for a specific user to trigger a rule, despite being a member of a blocked role.
• AllowModBypass (boolean) - Specifies if those defined within the moderators list for the server should be exempt from triggering this rule. Defaults to true.

¹ A rule may either contain a whitelist or blacklist, but not both. ² Used only if a whitelist or blacklist have been specified.

Responses

A response is the action, or list of actions, to be executed when a rule is matched. Defining a response could be considered to be similar to typing out a command or a batch script, with certain responses requiring a number of parameters.

The following responses are currently implemented:

• ban - Immediately bans the user that triggered the rule.
• kick - Immediately kicks the user that triggered the rule.
• remove - Removes the message that triggered the rule.
  • Aliases: delete
• report target_entity - Sends a copy of the message that triggered the rule to the specified target.
• grantrole target_user role_ID - Adds the target_user to the given role defined by role_ID.
  • Aliases: addrole
• revokerole target_user role_ID - Removes the target_user from the given role defined by role_ID.
  • Aliases: delrole, removerole
• say target_entity message - Sends message to the given target_entity.
  • Aliases: send

In regards to responses that accept target parameters, it is possible to specify the target to be the user who triggered the rule or the channel in which the rule was triggered in. This is done by specifying the parameter as @_ or #_, respectively. The sample above shows an example of this.

Additionally, targets may be defined in the same type of format accepted within entity lists. This is also shown in the above example.