Auto Moderation

Reference for Discord’s Auto Moderation system, rule objects, and management endpoints.

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

Rules can be configured to automatically execute actions when they trigger. For example, a rule can block a message before it’s sent if it contains a certain keyword.

Auto moderation rule object

Auto moderation rule structure

id · snowflake · required

The ID of this rule.

guild_id · snowflake · required

The ID of the guild this rule belongs to.

name · string · required

The rule name.

creator_id · snowflake · required

The user who first created this rule.

event_type · integer · required

The rule event type.

trigger_type · integer · required

The rule trigger type.

trigger_metadata · object · required

The rule trigger metadata. Different fields are relevant based on trigger_type.

actions · array of action objects · required

The actions which will execute when the rule is triggered.

enabled · boolean · required

Whether the rule is enabled.

exempt_roles · array of snowflakes · required

Role IDs that should not be affected by the rule. Maximum of 20.

exempt_channels · array of snowflakes · required

Channel IDs that should not be affected by the rule. Maximum of 50.

Example auto moderation 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"]
}

---

Trigger types

Characterizes the type of content which can trigger the rule.

Trigger type	Value	Description	Max per guild
KEYWORD	1	Check if content contains words from a user-defined list of keywords	6
SPAM	3	Check if content represents generic spam	1
KEYWORD_PRESET	4	Check if content contains words from internal pre-defined wordsets	1
MENTION_SPAM	5	Check if content contains more unique mentions than allowed	1
MEMBER_PROFILE	6	Check if member profile contains words from a user-defined list of keywords	1

---

Trigger metadata

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

Field	Type	Associated trigger types	Description
keyword_filter	array of strings	KEYWORD, MEMBER_PROFILE	Substrings which will be searched for in content. Maximum of 1000.
regex_patterns	array of strings	KEYWORD, MEMBER_PROFILE	Regular expression patterns matched against content. Maximum of 10.
presets	array of keyword preset types	KEYWORD_PRESET	The internally pre-defined wordsets searched for in content.
allow_list	array of strings	KEYWORD, KEYWORD_PRESET, MEMBER_PROFILE	Substrings which should not trigger the rule. Maximum of 100 or 1000.
mention_total_limit	integer	MENTION_SPAM	Total number of unique role and user mentions allowed per message. Maximum of 50.
mention_raid_protection_enabled	boolean	MENTION_SPAM	Whether to automatically detect mention raids.

Each keyword_filter entry can be a phrase containing multiple words. Wildcard symbols can be used to customize matching. Each keyword must be 60 characters or less.

Only Rust-flavored regex is supported for regex_patterns. Each regex pattern must be 260 characters or less.

Trigger metadata field limits

Field	Trigger types	Max array length	Max characters per string
keyword_filter	KEYWORD, MEMBER_PROFILE	1000	60
regex_patterns	KEYWORD, MEMBER_PROFILE	10	260
allow_list	KEYWORD, MEMBER_PROFILE	100	60
allow_list	KEYWORD_PRESET	1000	60

---

Keyword preset types

Preset type	Value	Description
PROFANITY	1	Words that may be considered forms of swearing or cursing
SEXUAL_CONTENT	2	Words that refer to sexually explicit behavior or activity
SLURS	3	Personal insults or words that may be considered hate speech

---

Event types

Indicates in what event context a rule should be checked.

Event type	Value	Description
MESSAGE_SEND	1	When a member sends or edits a message in the guild
MEMBER_UPDATE	2	When a member edits their profile

---

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

Keyword	Matches
cat*	catch, Catapult, CAttLE
tra*	train, trade, TRAditional
the mat*	the matrix

Suffix — word must end with the keyword

Keyword	Matches
*cat	wildcat, copyCat
*tra	extra, ultra, orchesTRA
*the mat	breathe mat

Anywhere — keyword can appear anywhere in the content

Keyword	Matches
*cat*	location, eduCation
*tra*	abstracted, outrage
*the mat*	breathe matter

Whole word — keyword is a full word or phrase surrounded by whitespace

Keyword	Matches
cat	cat
train	train
the mat	the mat

---

Auto moderation action object

An action which will execute whenever a rule is triggered.

Action structure

type · integer · required

The action type.

metadata · action metadata object

Additional metadata needed during execution for this specific action type. Can be omitted based on type. Optional field.

Action types

Action type	Value	Description
BLOCK_MESSAGE	1	Blocks a member’s message and prevents it from being posted. A custom explanation can be shown to members whenever their message is blocked.
SEND_ALERT_MESSAGE	2	Logs user content to a specified channel.
TIMEOUT	3	Timeout user for a specified duration. Only usable with KEYWORD and MENTION_SPAM rules. Requires the MODERATE_MEMBERS permission.
BLOCK_MEMBER_INTERACTION	4	Prevents a member from using text, voice, or other interactions.

Action metadata

Additional data used when an action executes. Different fields apply based on action type.

Field	Type	Associated action types	Description	Constraints
channel_id	snowflake	SEND_ALERT_MESSAGE	Channel to which user content should be logged.	Existing channel
duration_seconds	integer	TIMEOUT	Timeout duration in seconds.	Maximum of 2,419,200 seconds (4 weeks)
custom_message	string	BLOCK_MESSAGE	Additional explanation shown to members whenever their message is blocked.	Maximum of 150 characters

---

Permission requirements

Users must have the MANAGE_GUILD permission to access all Auto Moderation resources. Some action types require additional permissions — for example, the TIMEOUT action type requires MODERATE_MEMBERS.

---

List auto moderation rules for guild

GET /guilds/{guild.id}/auto-moderation/rules

Get a list of all rules currently configured for the guild. Returns a list of auto moderation rule objects for the given guild.

Requires the MANAGE_GUILD permission.

Get auto moderation rule

GET /guilds/{guild.id}/auto-moderation/rules/{auto_moderation_rule.id}

Get a single rule. Returns an auto moderation rule object.

Requires the MANAGE_GUILD permission.

Create auto moderation rule

POST /guilds/{guild.id}/auto-moderation/rules

Create a new rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Create gateway event.

Requires the MANAGE_GUILD permission. This endpoint supports the X-Audit-Log-Reason header.

JSON params

name · string · required

The rule name.

event_type · integer · required

The event type.

trigger_type · integer · required

The trigger type.

trigger_metadata · object

The trigger metadata. Can be omitted based on trigger_type.

actions · array of action objects · required

The actions which will execute when the rule is triggered.

enabled · boolean · default: "false"

Whether the rule is enabled.

exempt_roles · array of snowflakes

Role IDs that should not be affected by the rule. Maximum of 20.

exempt_channels · array of snowflakes

Channel IDs that should not be affected by the rule. Maximum of 50.

See trigger types for limits on how many rules of each trigger type can be created per guild.

Modify auto moderation rule

PATCH /guilds/{guild.id}/auto-moderation/rules/{auto_moderation_rule.id}

Modify an existing rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Update gateway event.

Requires MANAGE_GUILD permission. All parameters are optional. This endpoint supports the X-Audit-Log-Reason header.

JSON params

name · string

The rule name.

event_type · integer

The event type.

trigger_metadata · object

The trigger metadata. Can be omitted based on trigger_type.

actions · array of action objects

The actions which will execute when the rule is triggered.

enabled · boolean

Whether the rule is enabled.

exempt_roles · array of snowflakes

Role IDs that should not be affected by the rule. Maximum of 20.

exempt_channels · array of snowflakes

Channel IDs that should not be affected by the rule. Maximum of 50.

Delete auto moderation rule

DELETE /guilds/{guild.id}/auto-moderation/rules/{auto_moderation_rule.id}

Delete a rule. Returns 204 No Content on success. Fires an Auto Moderation Rule Delete gateway event.

Requires the MANAGE_GUILD permission. This endpoint supports the X-Audit-Log-Reason header.