Full AutoModerator documentation
This page is a full specification of AutoModerator's capabilities and behavior, and the syntax for utilizing it. If you are new to AutoModerator and are looking for information about how to set it up and write basic rules, please see the Introduction page and Writing Basic Rules.
General knowledge/behavior
- AutoModerator's configuration is kept on a sub's wiki, at the "config/automoderator" page.
- Rules that may result in an item being removed (action of
remove
,spam
, orfilter
) are always checked before all other rules. - By default, submissions and comments made by moderators of the sub will not be checked against any rules that may cause the post to be removed or reported. You can override this behavior with the
moderators_exempt
flag. - AutoModerator tries to avoid contradicting other moderators, and will not approve items that have already been removed by another moderator, or remove items that have already been approved by another mod.
- AutoModerator will not approve items posted by users that are banned site-wide on saidit unless the approval rule includes a check against author name.
- Approval conditions will not re-approve reported items unless the rule includes a
reports:
check. - Approval actions will only be performed on items that need to be approved to change their state. That is, only items that were automatically removed by saidit's spam-filter, or reported items (as long as the rule includes a
reports:
check as mentioned above). - AutoModerator will not leave an entry in the moderation log when it sets flair or distinguishes its comments. All other actions (removals, approvals, etc.) will be logged as with any other moderator.
Syntax
AutoModerator rules are defined using YAML, so for full details about allowable syntax you can look up examples or the YAML specification (kind of a difficult/technical document). Some of the most important things to know for AutoModerator specifically:
Rules must be separated by a line starting with exactly 3 hyphens - ---
.
Comments can be added by using the #
symbol. Generally everything after a #
on a line will be treated as a comment and ignored, unless the #
is inside a string or otherwise part of actual syntax.
Strings do not generally need to be quoted, but it is usually safest to put either single or double quotes around a string, especially if it includes any special characters at all. For example, the quotes here are unnecessary but encouraged:
title: ["red", "blue", "green"]
If you do not use quotes, there are certain types of strings that the YAML parser will try to automatically convert, which can result in unexpected behavior. In general, these include strings of numbers that start with 0
or 0x
, strings that consist of only numbers and underscores, and the words true
, false
, on
, off
, yes
, no
. If in doubt, it is always safest to use quotes.
When defining regular expressions inside a search check, you should always surround the regular expression with quotes, but single quotes are highly encouraged. This avoids needing to double-escape. For example, this check includes the exact same regex twice, but the double-quoted version requires double-escaping all the special characters:
title (regex): ["\\[\\w+\\]", '\[\w+\]']
Note that if you need to include a single quote inside a single-quoted string, the way to do so is by typing two single quotes in a row, not with a backslash. For example: 'it''s done like this'
.
Multi-line strings can be defined as well, this is used almost exclusively for defining multi-line comments to post or messages/modmails to send. The syntax for a multi-line string is to have a single pipe character (|
) on the first line, and then indent all lines of the multi-line string below and inside. For example:
comment: |
This is a multi-line comment.
It has multiple lines.
You can use **markdown** inside here too.
Lists of items can be defined in two different ways. The most compact method is inside square brackets, comma-separated:
title: ["red", "green", "blue"]
The other method is by indenting the list of items below, with a hyphen at the start of each line. This format is often better for longer or more complex items, or if you want to add a comment on individual items:
title:
- "red" # like apples
- "green" # like grapes
- "blue" # like raspberries
Both formats are exactly the same from AutoModerator's perspective, but one can often be far easier to read than the other.
You should always avoid defining the same thing twice inside a particular rule. This will just end up with the second definition overwriting the first one. For example, a rule like this will end up only affecting youtube submissions and not imgur:
domain: imgur.com
domain: youtube.com
action: remove
Top-level-only checks/actions
The following checks/actions are only available in the top level of a rule, and cannot be included inside sub-groups:
type
- defines the type of item this rule should be checked against. Valid values arecomment
,submission
,text submission
,link submission
,crosspost submission
, orany
(default).priority
- must be set to a number. Can be used to define the order that rules should be checked in (though they will still always be checked in two separate groups - rules that might cause any sort of removal first - ones with action ofremove
,spam
orfilter
, and then all others). Rules with higher priority values will be checked first. If a rule does not have a priority defined, it defaults to zero. Negative priority values can be used as well to specify that certain rules should be checked after ones with no defined priority value.moderators_exempt
- true/false - Defines whether the rule should be skipped when the author of the item is a moderator of the sub. Mods are exempt from rules that can result in a removal or report by default, so set this to false to override that behavior, or set it to true to make them exempt from any other rules.comment
- Text of a comment to post in response to an item that satisfies the rule's conditions. Supports placeholders.comment_stickied
- true/false - if set to true, the comment automoderator posts in response to an item will be stickied to the top of the submission (will have no effect on non-submissions, as the comment must be top-level)modmail
- Text of a modmail to send to the moderators when an item satisfies the rule's conditions. Supports placeholders.modmail_subject
- If a modmail is sent, the subject of that modmail. Defaults to "AutoModerator notification" if not set. Supports placeholders.message
- Text of a message to send to the author of an item that satisfies the rule's conditions. Supports placeholders.message_subject
- If a message is sent, the subject of that message. Defaults to "AutoModerator notification" if not set. Supports placeholders.
Sub-groups
AutoModerator rules also support "sub-groups" of checks and actions that apply to things that are related to the main item being targeted by the rule. There are currently four supported sub-groups, author
, crosspost_author
, crosspost_sub
and parent_submission
. parent_submission
can be used only if the main item is a comment, but author
and crosspost_author
can always be used. The author
targets the author of the new submission or comment in question, the crosspost_author
targets the author of the original submission. If crosspost_author
is being used and the base item being checked isn't a crosspost, then the rule will not be applied. crosspost_sub
targets the sub of the original post. Checks and actions inside the sub-group should be indented below and inside it. For example, here is a rule that utilizes both sub-groups to set a submission's flair text to "Possible Repost" if a user with the "trusted" flair css class makes a top-level comment inside it including the word "repost":
type: comment
body: "repost"
is_top_level: true
author:
flair_css_class: "trusted"
parent_submission:
set_flair: "Possible Repost"
Search Checks
These checks can be used to look for words/phrases/patterns in different fields.
- Search checks can be reversed by starting the name with
~
. If this is done, the check will only be satisfied if the fields being searched do NOT contain any of the options. - Search checks can be combined by joining them with
+
. If this is done, the check will be satisfied if ANY of the fields joined together contain one of the options. - Search checks are case-insensitive by default.
Available fields to check against:
For all submissions (base item or parent_submission sub-group):
id
- the submission's base-36 ID.title
- the submission's titledomain
- the submission's domain. For a text submission, this is "self.subname"url
- the submission's full url. Cannot be checked for text submissions.body
- for text submissions, the full text of the post. Cannot be checked for link submissions.flair_text
- the text of the submission's link flairflair_css_class
- the css class of the submission's link flairflair_template_id
- the template id of the submission's link flair
For crossposts submissions:
The following fields will always be checked against the fields of the original submission.
domain
- if the submission is a crosspost, then check the domain of the original submissionurl
- if the submission is a crosspost, then check the full url of the original submissionbody
- if the submission is a crosspost, then check the body of the original submission
In addition, we have the following fields that will check the original submission. If the submission isn't a crosspost, then a rule with any of these attributes will be ignored.
crosspost_id
- if the submission is a crosspost, then check the base-36 ID of the original submissioncrosspost_title
- if the submission is a crosspost, then check the title of the original submission
Media checks
On submissions, it is also possible to do some checks against the "media object" that gets embedded in saidit. If the submission is a crosspost, then the values of the original submission are checked. The media data that is available comes from embed.ly, so you can see what information is available for a specific link by testing it here: http://embed.ly/extract
media_author
- the author name returned from embed.ly (usually the username of the uploader on the media site)media_author_url
- the author's url returned from embed.ly (usually the link to their user page on the media site)media_title
- the media title returned from embed.lymedia_description
- the media description returned from embed.ly
For comments (base item only):
id
- the comment's base-36 IDbody
- the full text of the comment.
For users (inside author or crosspost_author sub-group):
id
- the user's base-36 IDname
- the user's nameflair_text
- the text of the user's flair in the subflair_css_class
- the css class of the user's flair in the subflair_template_id
- the template id of the user's flair in the sub
For subs (inside crosspost_sub):
name
- the name of the sub where the original submission was posted
Matching modifiers
These modifiers change how a search check behaves. They can be used to ensure that the field being searched starts with the word/phrase instead of just including it, allow you to define regular expressions, etc.
To specify modifiers for a check, put the modifiers in parentheses after the check's name. For example, a body+title
check with the includes
and regex
modifiers would look like:
body+title (includes, regex): ["whatever", "who cares?"]
Match search methods
These modifiers change how the search options for looked for inside the field, so only one of these can be specified for a particular match.
includes-word
- searches for an entire word matching the textincludes
- searches for the text, regardless of whether it is included inside other wordsstarts-with
- only checks if the subject starts with the textends-with
- only checks if the subject ends with the textfull-exact
- checks if the entire subject matches the text exactlyfull-text
- similar tofull-exact
, except punctuation/spacing on either end of the subject is not considered
Other modifiers
regex
- considers the text being searched for to be a regular expression (using standard Python regex syntax), instead of literal text to findcase-sensitive
- makes the search case-sensitive, so text with different capitalization than the search value(s) will not be considered a match
If you do not specify a search method modifier for a particular check, it will default to one depending on which field you are checking. Note that if you do any joined search check (multiple fields combined with +
), the default is always includes-word
. Otherwise, if you are checking a single subject field, the defaults are as follows:
domain
: special check that looks only for the exact domain or a subdomain of itid
:full-exact
url
:includes
flair_text
:full-exact
flair_css_class
:full-exact
flair_template_id
:full-exact
media_author
:full-exact
media_author_url
:includes
All other fields default to includes-word
.
Non-searching checks
Other checks that can be used that are not search checks (so do not take a value or list of values to look for, cannot be joined with +
or reversed with ~
, etc.).
For submissions (base item or parent_submission sub-group):
reports
- must be set to a number. The minimum number of reports the submission must have to trigger the rule.body_longer_than
- must be set to a number. The submission's body must be longer than this number of characters to trigger the rule (spacing and punctuation characters on either end are not counted).body_shorter_than
- must be set to a number. The submission's body must be shorter than this number of characters to trigger the rule (spacing and punctuation characters on either end are not counted).is_edited
- true/false - if set to true, submissions will only trigger the rule if they have been edited. if set to false, submissions will only trigger the rule if they have NOT been edited (so new submissions will be checked against the rule, but they will not be re-checked on edit).is_original_content
- true/false - if set to true, submissions will only trigger the rule if they are flagged asOC
(original content). If set to false, submission will only trigger the rule if the are NOT flagged asOC
.
For comments (base item only):
reports
- must be set to a number. The minimum number of reports the comment must have to trigger the rule.body_longer_than
- must be set to a number. The comment's body must be longer than this number of characters to trigger the rule (spacing and punctuation characters on either end are not counted).body_shorter_than
- must be set to a number. The comment's body must be shorter than this number of characters to trigger the rule (spacing and punctuation characters on either end are not counted).is_top_level
- true/false - if set to true, comments will only trigger the rule if they are top-level comments (posted in reply to the submission itself, not to another comment). If set to false, comments will only trigger the rule if they are NOT top-level comments (posted in reply to another comment).is_edited
- if set to true, comments will only trigger the rule if they have been edited. If set to false, comments will only trigger the rule if they have NOT been edited (so new comments will be checked against the rule, but they will not be re-checked on edit).
For subs (inside crosspost_sub):
is_nsfw
- true/false - If true, will only match if the sub of the original submission is NSFW
For users (inside author or crosspost_author sub-group):
Karma/age threshold checks
These checks are most often used as "thresholds" - greater than or less than checks. They can be specified using the < or > symbol followed by the value to check if the author has more or less than. For example, to check if the author has less than 10 post karma, the check would be:
author:
post_karma: < 10
Note that due to the > symbol having a special meaning in YAML syntax, you must put quotes around a greater-than check, but it is not necessary for less-than checks. For example, a check to see if the author has more than 10 post karma would have to be written as:
author:
post_karma: '> 10'
The supported threshold checks are:
comment_karma
- compare to the author's comment karma (note that comment karma will not go below -100)post_karma
- compare to the author's post karma (note that post karma will not go below 0)combined_karma
- compare to the author's combined (comment karma + post karma, combination can not be below -100)account_age
- compare to the age of the author's account. This check also supports specifying a unit (default is days), so you can specify something likeaccount_age: < 60 hours
. Supported units are minutes, hours, days, weeks, months, and years.satisfy_any_threshold
- true/false - If true and any karma or age threshold checks are being done, only one of the checks will need to be successful. If false, ALL the checks will need to be satisfied for the rule to trigger (this is the default behavior).
Other user checks
is_gold
- true/false - If true, will only match if the author has saidit gold. If false, will only match if they do not have gold.is_submitter
- true/false - (only relevant when checking comments) If true, will only match if the author was also the submitter of the post being commented inside. If false, will only match if they were not.is_contributor
- true/false - if true, will only match if the author is a contributor/"approved submitter" in the sub. If false, will only match if they are not.is_moderator
- true/false - if true, will only match if the author is a moderator of the sub. If false, will only match if the author is NOT a moderator of the sub.
Actions
For submissions (base item or parent_submission sub-group):
action
- A moderation action to perform on the item. Valid values areapprove
,remove
,spam
,filter
, orreport
.filter
is a unique action to AutoModerator, and will remove the post but keep it in the modqueue and unmoderated pages.action_reason
- Displays in the moderation log as a reason for why a post was approved or removed. If the action isreport
, displays as the report reason instead. Supports placeholders.set_flair
- Takes either a single string, a list of two strings or a dictionary. If given a single string, the submission's flair text will be set to the string. If given two strings, the first string will be used for the flair text, and the second string for the flair css class. If given a dictionary, the keys will be one of 'text', 'css_class', or 'template_id'. If set, the value of 'text' will be used for the flair text and the value of 'css_class' will be used for the css class. When using the dictionary syntax, 'template_id' must be set, and the value of 'template_id' will be used to set the flair template (template Ids are accessible in Post Flair and User Flair sections of Mod Tools). The flair text, flair css class and flair template id can include placeholders.overwrite_flair
- true/false - If true, aset_flair
action will overwrite any previous link flair on the submission. If false (same as default behavior), any existing flair will not be overwritten.set_sticky
- true/false or a number - Sets or unsets the matched submission as a sticky in the sub. If you use a number (for exampleset_sticky: 1
), the post will replace any existing sticky in that slot. Usingtrue
will work the same as clicking the "sticky this post" link on the post - it will go into the bottom sticky slot (replacing a post that's already there, if necessary).set_nsfw
- true/false - Enables (true) or disables (false) the NSFW flag on the submission.set_spoiler
- true/false - Enables (true) or disables (false) the spoiler flag on the submission.set_contest_mode
- true/false - Enables (true) or disables (false) contest mode for the submission's comments.set_original_content
- true/false – Enables (true) or disables (false) the OC (original content) flag on the submission.set_suggested_sort
- Sets the item's suggested comment sort. Valid values arebest
,new
,qa
,top
,controversial
,hot
,old
,random
andblank
(confidence
is also available as an alias forbest
). Setting toblank
is different than not setting at all - it will make it so that the user's default sort is used instead of the sub's (if the sub has one).set_locked
- true/false - Locks or unlocks the submission.
For comments (base item only):
action
- A moderation action to perform on the item. Valid values areapprove
,remove
,spam
, orreport
report_reason
- If the action isreport
, sets the report reason that will be used. Supports placeholders.
For users (inside author or crosspost_author sub-group):
set_flair
- Takes either a single string, a list of two strings or a dictionary. If given a single string, the submission's flair text will be set to the string. If given two strings, the first string will be used for the flair text, and the second string for the flair css class. If given a dictionary, the keys will be one of 'text', 'css_class', or 'template_id'. If set, the value of 'text' will be used for the flair text and the value of 'css_class' will be used for the css class. When using the dictionary syntax, 'template_id' must be set, and the value of 'template_id' will be used to set the flair template (template Ids are accessible in Post Flair and User Flair sections of Mod Tools).overwrite_flair
- true/false - If true, aset_flair
action will overwrite any previous user flair. If false (same as default behavior), any existing flair will not be overwritten.
Other directives
ignore_blockquotes
- true/false - If set to true, any text inside blockquotes will not be considered by this rule when doing search checks againstbody
, or counting length withbody_shorter_than
/body_longer_than
.
Placeholders
When used inside a string that supports placeholders, these will be replaced with the appropriate value. For crossposts, the {{body}}
, {{domain}}
, and {{url}}
are replaced by the value of the original submission. This allows including information about a post or its author in modmail or report reasons, setting flair to something based on the post that triggered it to be set, etc.
{{author}}
- the author's name (do/u/{{author}}
for a link to the author's user page){{author_flair_text}}
- the author's flair text (will be replaced with nothing if they have no flair set, or have it disabled){{author_flair_css_class}}
- the author's flair CSS class (will be replaced with nothing if they have no flair set, or have it disabled){{author_flair_template_id}}
- the author's template id (will be replaced with nothing if they have no flair set, or have it disabled){{body}}
- the full body text of the text submission or comment{{permalink}}
- a link to the item{{sub}}
- the sub's name (do/s/{{sub}}
for a link to the sub){{kind}}
- replaced with "submission" for submissions or "comment" for comments{{title}}
- the submission's title{{domain}}
- the submission's domain{{url}}
- the submission's full url
Media placeholders
Note that if you use a media placeholder anywhere in a rule, it will make it so that the rule is not applied to any objects where this data is not available.
{{media_author}}
- the media's author username{{media_author_url}}
- the media's author url{{media_title}}
- the media's title{{media_description}}
- the media's description
Match placeholders
There is also one other special type of placeholder that can be used to show information about which words/phrases were matched by a search check on the base item (not search checks inside a sub-group like author:
or parent_submission:
). In its most basic form it is simply {{match}}
and will be replaced with whichever option in your search check matched something in the item. For example, this condition would give a submission a flair css class corresponding to the color that they use in their title:
title: ["red", "green", "blue"]
set_flair: ["", "{{match}}"]
In the case of multiple search checks, you must specify which check to take the match from, or you may end up with unexpected behavior. For example, if the same rule also includes a search on domain
, you should specify that you want the match from the title
search with {{match-title}}
:
title: ["red", "green", "blue"]
domain: [youtube.com, youtu.be]
set_flair: ["", "{{match-title}}"]
And finally, it is also possible to use the match placeholder to specify individual capture groups from a regular expression search check. This is done by adding the number of the capture group at the end of the placeholder, but be aware that {{match}}
is the same as {{match-1}}
, and will be replaced with the entire matched word/phrase. Capture groups defined inside your regex with parentheses start at {{match-2}}
. You can also specify the specific search match along with this, such as {{match-title-2}}
.
Standard conditions
Standard conditions allow you to make use of some pre-defined checks such as "image hosting sites" and "video hosting sites" that maintain a list of common domains, so that you do not need to manually define your own list. To use a standard condition, simply define standard:
along with the check's name. You can only define a single standard condition inside a rule. For example, to remove submissions from common image hosts:
standard: image hosting sites
action: remove
The available standard conditions are:
image hosting sites
- will match link submissions from common image hosting domainsdirect image links
- will match link submissions that link directly to image files (PNG, JPG, GIF, GIFV)video hosting sites
- will match link submissions from common video hosting domainsstreaming sites
- will match link submissions from common streaming domainscrowdfunding sites
- will match link submissions from common crowdfunding domainsmeme generator sites
- will match link submissions from common meme-generator sitesfacebook links
- will match submissions or comments including links to Facebookamazon affiliate links
- will match submissions or comments including Amazon links with an affiliate code
If you want to look at the specifics of what a particular standard condition will match, the definitions are available for reference on the standard conditions page.
revision by — view source