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

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.

AutoMod Alert

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.

AutoMod Alert Embed Structure

AutoMod Profile Update Type

AutoMod Quarantine User Reason

AutoMod Quarantine User Action

AutoMod Quarantine Event Type

AutoMod Voice Channel Status Outcome

AutoMod Alert Actions Execution Structure

AutoMod Alert Action Type

AutoMod Alert Action Structure

Example AutoMod Alert Embed

{
  "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
    }
  ]
}

AutoMod Incident Notification

Sent when a guild incident activity alert is triggered.

AutoMod Incident Notification Embed Structure

AutoMod Incident Notification Type

AutoMod Raid Type

AutoMod Raid Resolution Reason

Example AutoMod Incident Notification Embed

{
  "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
    }
  ]
}

AutoMod Rule Object

AutoMod Rule Structure

Example AutoMod Rule

{
  "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"]
}

AutoMod Trigger Type

Characterizes the type of content which can trigger the rule.

AutoMod Trigger Metadata

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.

AutoMod Keyword Preset Type

AutoMod Event Type

Indicates in what event context a rule should be checked.

AutoMod Keyword Matching Strategies

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

AutoMod Action Object

An action which will execute whenever a rule is triggered.

AutoMod Action Structure

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

AutoMod Action Type

¹ 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.

AutoMod Action Metadata

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

AutoMod Incidents Data Object

AutoMod Incidents Data Structure

Example AutoMod Incidents Data

{
  "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"
}

Endpoints

Get Guild AutoMod Rules

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

Get Guild AutoMod Rule

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

Create Guild AutoMod Rule

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.

JSON Params

¹ 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.

Modify Guild AutoMod Rule

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.

JSON Params

¹ 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.

Delete Guild AutoMod Rule

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.

Execute AutoMod Alert Action

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.

JSON Params

Modify AutoMod Incident Actions

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

JSON Params

Response Body

Example Response

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

Resolve AutoMod Incident

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

JSON Params

Report AutoMod Incident

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

Clear Mention Raid Incident

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