Auto Moderation

Auto Moderation, or AutoMod, is a feature which allows each guild to set up rules that trigger based on some criteria. For example, a rule can trigger whenever a message contains a specific keyword.

Rules can be configured to automatically execute actions whenever they trigger. For example, if a user tries to send a message which contains a certain keyword, a rule can trigger and block the message before it is sent.

AutoMod system messages are sent as standard messages in the guild with the AUTO_MODERATION_ACTION message type. If no user is associated with the system message, the author is the AutoMod system account (1008776202191634432).

These messages have a special embed structure which contains information about the action that was taken. The custom embed fields below are collapsed as a list of key-value pairs into the fields array on the embed object.

Sent when a SEND_ALERT_MESSAGE action type is triggered.

The author of the message is the user which generated the content that triggered the rule. The embed description contains the user message content that triggered the rule, if applicable.

{
  "type": "auto_moderation_message",
  "description": "can i say alien 🥺",
  "fields": [
    {
      "name": "rule_name",
      "value": "No aliens",
      "inline": false
    },
    {
      "name": "channel_id",
      "value": "1121695809839308901",
      "inline": false
    },
    {
      "name": "decision_id",
      "value": "22a2df4cf7904b81a17faa3e3930af7d",
      "inline": false
    },
    {
      "name": "keyword",
      "value": "alien",
      "inline": false
    },
    {
      "name": "keyword_matched_content",
      "value": "alien",
      "inline": false
    },
    {
      "name": "flagged_message_id",
      "value": "1200705269110411274",
      "inline": false
    },
    {
      "name": "timeout_duration",
      "value": "600",
      "inline": false
    },
    {
      "name": "alert_actions_execution",
      "value": "{\"v\": 0, \"actions\": {\"3\": {\"actor\": \"852892297661906993\", \"ts\": \"2024-01-27T07:34:12.145393+00:00\"}, \"1\": {\"actor\": \"852892297661906993\", \"ts\": \"2024-01-27T07:38:29.292345+00:00\"}}}",
      "inline": false
    }
  ]
}

Sent when a guild incident activity alert is triggered.

{
  "type": "auto_moderation_notification",
  "fields": [
    {
      "name": "notification_type",
      "value": "raid",
      "inline": false
    },
    {
      "name": "raid_datetime",
      "value": "2023-08-15 22:25:33.184657+00:00",
      "inline": false
    },
    {
      "name": "raid_type",
      "value": "JOIN_RAID",
      "inline": false
    },
    {
      "name": "join_attempts",
      "value": "25",
      "inline": false
    },
    {
      "name": "dms_sent",
      "value": "0",
      "inline": false
    },
    {
      "name": "resolved_reason",
      "value": "LEGITIMATE_ACTIVITY",
      "inline": false
    }
  ]
}

{
  "id": "969707018069872670",
  "guild_id": "613425648685547541",
  "name": "Keyword Filter 1",
  "creator_id": "423457898095789043",
  "trigger_type": 1,
  "event_type": 1,
  "actions": [
    {
      "type": 1,
      "metadata": { "custom_message": "Please keep financial discussions limited to the #finance channel" }
    },
    {
      "type": 2,
      "metadata": { "channel_id": "123456789123456789" }
    },
    {
      "type": 3,
      "metadata": { "duration_seconds": 60 }
    }
  ],
  "trigger_metadata": {
    "keyword_filter": ["cat*", "*dog", "*ana*", "i like c++"],
    "regex_patterns": ["(b|c)at", "^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"]
  },
  "enabled": true,
  "exempt_roles": ["323456789123456789", "423456789123456789"],
  "exempt_channels": ["523456789123456789"]
}

Characterizes the type of content which can trigger the rule.

Additional data used to determine whether a rule should be triggered. Different fields are relevant based on the trigger type.

¹ A keyword can be a phrase which contains multiple words. Wildcard symbols can be used to customize how each keyword will be matched. Each keyword must be 60 characters or less.

² Only Rust flavored regex is currently supported, which can be tested in online editors such as Rustexp. Each regex pattern must be 260 characters or less.

³ Each allow_list keyword can be a phrase which contains multiple words. Wildcard symbols can be used to customize how each keyword will be matched. Rules with KEYWORD trigger types accept a maximum of 100 keywords. Rules with KEYWORD_PRESET trigger types accept a maximum of 1000 keywords.

Indicates in what event context a rule should be checked.

Use the wildcard symbol (*) at the beginning or end of a keyword to define how it should be matched. All keywords are case insensitive.

Prefix - Word must start with the keyword

Suffix - Word must end with the keyword

Anywhere - Keyword can appear anywhere in the content

Whole Word - Keyword is a full word or phrase and must be surrounded by whitespace

An action which will execute whenever a rule is triggered.

¹ See the "Action Type" column in action metadata to understand which type values require metadata to be set.

¹ Only a SEND_ALERT_MESSAGE action can be set up for GUILD_POLICY trigger types.

² A TIMEOUT_USER action can only be set up for KEYWORD and MENTION_SPAM trigger types. The MODERATE_MEMBERS permission is required to use the TIMEOUT_USER action type.

³ A QUARANTINE_USER action can only be set up for USER_PROFILE trigger types. The MODERATE_MEMBERS permission is required to use the QUARANTINE_USER action type.

Additional data used when an action is executed. Different fields are relevant based on the action type.

{
  "raid_detected_at": "2024-01-01T18:00:00.000000+00:00",
  "dm_spam_detected_at": "2024-01-01T18:00:00.000000+00:00",
  "invites_disabled_until": "2024-01-01T18:00:00.000000+00:00",
  "dms_disabled_until": "2024-01-01T18:00:00.000000+00:00"
}

Returns a list of automod rule objects for the configured rules in the guild. Requires the MANAGE_GUILD permission.

Returns an automod rule object for the given rule ID in the guild. Requires the MANAGE_GUILD permission.

Creates a new automod rule in the guild. Requires the MANAGE_GUILD permission. Returns an automod rule on success. Fires an Auto Moderation Rule Create Gateway event.

¹ See the "Trigger Types" column in trigger metadata to understand which trigger types require trigger_metadata to be set.

² Only applicable to KEYWORD, SPAM, KEYWORD_PRESET, MENTION_SPAM, and GUILD_POLICY trigger types.

Modifies an existing rule in the guild. Requires the MANAGE_GUILD permission. Returns an automod rule on success. Fires an Auto Moderation Rule Update Gateway event.

¹ See the "Trigger Types" column in trigger metadata to understand which trigger types require trigger_metadata to be set.

² Only applicable to KEYWORD, SPAM, KEYWORD_PRESET, MENTION_SPAM, and GUILD_POLICY trigger types.

Deletes a rule in the guild. Returns a 204 empty response on success. Requires the MANAGE_GUILD permission. Fires an Auto Moderation Rule Delete Gateway event.

Executes an alert action on an AutoMod alert. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires a Message Update Gateway event.

Sets the incident actions for the guild. Requires the MANAGE_GUILD permission. Fires a Guild Update Gateway event.

{
  "invites_disabled_until": "2024-01-01T18:00:00.000000+00:00",
  "dms_disabled_until": "2024-01-01T18:00:00.000000+00:00"
}

Resolves an AutoMod incident. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires a Message Update Gateway event.

Reports an ongoing raid AutoMod incident. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires a Message Create Gateway event.

Clears a mention raid AutoMod incident. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success.