# Watched Words Reference Guide **URL:** https://meta.discourse.org/t/watched-words-reference-guide/241735 **Category:** Site Management **Tags:** reference, watched-words, content **Created:** [October 12, 2022, 9:23pm UTC](https://meta.discourse.org/t/watched-words-reference-guide/241735 "2022-10-12T21:23:15Z") **Posts on this page:** 1 **Showing post:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [October 12, 2022, 9:23pm UTC](https://meta.discourse.org/t/watched-words-reference-guide/241735/1 "2022-10-12T21:23:16Z")
> 🔖 This is a #reference guide for describing how the Watched Words page functions and the different types of action types you can use to block specific words on a Discourse site. > > 🙋 Required user level: Administrator # Understanding Watched Words You can setup Watched Words to take actions based on words found in a topic or post (located at `.../admin/customize/watched_words` ). ![0fa98e1d-d611-4971-a78b-6dd736f7cd22](https://global.discourse-cdn.com/meta/original/4X/e/9/9/e9994d2d460a660ccef90afbd1f56bb6a9f7a376.png) There’s a max of 2000 words per type of action. On all actions, `*` can be used as a wildcard, and there’s an option to select if the watched words are case-sensitive. By default, the watched words are hidden. Checking the “show words” checkbox will display them and allow you to delete them. Using the search field will also reveal any matching words. Lists of Watched Words can be uploaded in bulk using the **“Add from File”** button, and a list of Watched Words for any action type can be downloaded from Discourse with the **“Download”** button. CSV is the required file format for uploading watched words in bulk. ### CSV Format for Bulk Upload The CSV file is uploaded per action type — there is no column for the action type itself. The format is the same for all action types: up to three columns. | Column | Contents | Notes | | --- | --- | --- | | 1 | Word or phrase | Required for all action types | | 2 | Replacement value | Required for **Replace** , **Link** , and **Tag** — rows missing this value are skipped. Ignored for all other action types. | | 3 | Case sensitivity | Optional for all action types. The exact string `true` enables case sensitivity; any other value, or a blank/absent column, means case-insensitive. `TRUE` and `True` are also accepted. | **Example:** ```plaintext badword another bad phrase *wildcard* CaseSensitiveWord,,true oldword,newword colour,color DontTouchThis,leave it alone,true ``` > ℹ A few things worth knowing: > > - The **“Download”** button does **not** export the case-sensitivity setting. If you download a list and re-upload it, all words will revert to case-insensitive unless you manually add `true` in column 3 before re-importing. > - Words and replacement values are each limited to **100 characters**. > - If a word or replacement contains a comma, wrap it in double-quotes — standard CSV quoting rules apply (e.g. `"hello, world",replacement`). All actions also have a **“Test”** button that can be used to test if a specific word or phrase contains any watched words. _Example of a matched watched word phrase_ ![image](https://global.discourse-cdn.com/meta/original/4X/3/2/1/32104cab99508c706ea019f76038bb1c658eb4c5.png) _Example of a phrase with no matches_ ![image](https://global.discourse-cdn.com/meta/original/4X/9/0/1/9014d688d06d05fe8acff6f9d2661286763bae20.png) # Action Types The Watched Words page allows you to take the following types of actions on matched words: > ℹ A Watched Word can only exist in one action type list. If a duplicate word is added to a second list it will be removed from the previous list. ### Block Prevents topics or posts containing these words from being posted at the time they are submitted by blocking the entire topic / post. The user will see an error message when they try to submit their post. Staff posts (admins and moderators) will not be blocked by watched words. ### Censor Allows posts containing these words, but replace the words with characters that hide the censored words. Censored words will be replaced with blocks. (Ex: ■■■■■■■■) ### Require Approval Posts containing these words will require approval by staff before they can be seen. Upon submitting a post with a word with this action type, the post will be hidden until staff reviews it. Staff posts (admins and moderators) will not be scanned for require approval words. ### Flag Allows posts containing these words, but flags them so moderators can review them. A post with a flagged word will appear normally but be submitted for review. The reviewer will have various options: ![2022-12-06_review-queue-approve-options](https://global.discourse-cdn.com/meta/original/4X/1/a/7/1a70b612025f88a5c36235f6a0ad23e005066c42.jpeg) If they hide the post, it will still be viewable but will look something like this: ![2022-12-06_in-review-queue](https://global.discourse-cdn.com/meta/original/4X/a/1/8/a18696ff6ed03cca91ea270e34d24c9ea777c5bf.jpeg) Clicking on the ‘View ignored content’ link will show the full contents, but still in the ‘post-hidden’ state. If they choose ‘Keep Post,’ or choose ‘Disagree’ from the options, the post will look like this: ![2022-12-06_reviewed-keep](https://global.discourse-cdn.com/meta/original/4X/c/9/f/c9fff870f693ceb7b0d254a7fe2011d97fcad12a.jpeg) Staff posts (admins and moderators) will not be scanned for flagged words. > ℹ You can also use the [Flag Post on Words Automation](https://meta.discourse.org/t/discourse-automation/195773#available-scripts-3) to flag a topic on creation/edition if it contains specific words. ### Link Replaces words in posts with links. More commonly used to replace common words with links to specific topics or external URLs instead of censoring words. If no Link URL is selected when adding a word to this type of action, the homepage of the Discourse site will automatically be used as the link to replace the word. ![image](https://global.discourse-cdn.com/meta/original/4X/3/f/9/3f99bd33a2dba1101ef0a71cdee98bb340ed11f2.png) ### Replace Replaces words in posts with other words. If no Replacement word is selected when adding a word to this action, the word will be removed from the post, but no word replacement will take it’s place - the word will disappear from the post, and the post will be allowed to be submitted _(Not Recommended)_. ![image](https://global.discourse-cdn.com/meta/original/4X/c/5/7/c578ea44543286a83b6607123e50b154ed55d83c.png) The replace action type also has an `Outputs HTML in the replacement` checkbox option. ![image](https://global.discourse-cdn.com/meta/original/4X/e/f/9/ef9bf5cf8785dc9ee0811ac287f726f753b83ccc.png) This [feature](https://meta.discourse.org/t/replace-text-with-more-than-just-links/305672) allows admins to use HTML formatting when setting replacement text, which can be especially useful for creating links and adding styling emphasis to automatically substituted text. > ⚠ Remapping links through the use of watched words is not recommended, and can cause more trouble than intended. Therefore, the ability to remap links using Watched Words → Replace setting is intentionally disabled, and links will _not_ be remapped in topics or posts regardless of watched word settings. ### Tag Automatically tags topics with these words based on first post in the topic. One or more tags can be added for each word included in this action. ![image](https://global.discourse-cdn.com/meta/original/4X/c/8/1/c81f4a52e9abe8005d5305de1b381516744a947c.png) A tag _must_ be included when submitting a word with this type of action, otherwise you will receive an error. ![image](https://global.discourse-cdn.com/meta/original/4X/2/3/9/2396bc2463c15df0a96edf84020587a871ad45d5.png) Also note that when tagging topics with a watched word, the word must be included in the topic at the time the topic is posted in order for the topic to be correctly tagged. Editing a topic after it has been created with a watched word for a tag will **not** add the tag to the topic. ### Silence First posts of users containing these words will require approval by staff before they can be seen and the user will be automatically silenced. A user who uses a “silence” word on their first post will be silenced and the post be will sent to the moderation queue # Regex Expressions For information about using Regex Expressions with Watched Words see: > [@Using Regex with Watched Words](https://meta.discourse.org/t/using-regex-with-watched-words/241861): > > bookmark This topic explains how to effectively use regular expressions (regex) within Discourse’s [Watched Words](https://meta.discourse.org/t/watched-words-reference-guide/241735) feature. discourse For sites on our hosting, these settings are hidden. Customers on paid hosting plans may contact our support team at team@discourse.org, to request regex with Watched Words. Note: This feature is not available on our Free hosting plan. Regular expressions (regex) are a powerful tool for defining search patterns. You can use regex in the [Watched Words](https://meta.discourse.org/t/watched-words-reference-guide/241735) featur… # Watched Words and AI Triage In addition to manually configuring actions through Watched Words, Discourse can also integrate with AI tools to help automate and optimize moderation efforts in your community. By using the [Discourse AI - AI triage](https://meta.discourse.org/t/discourse-ai-ai-triage/281227) features you can setup **Toxicity Detection** and **NSFW Detection** to enhance your ability to identify and handle problematic content effectively. For full setup instructions, you can visit: - [Setting up toxicity detection in your community](https://meta.discourse.org/t/setting-up-toxicity-detection-in-your-community/320257) - [Setting up NSFW detection in your community](https://meta.discourse.org/t/setting-up-nsfw-detection-in-your-community/330196) # Watched Words in Personal Messages Watched Words of the ‘Flag’ type will be triggered in Personal Messages (PMs). See [the relevant section above](https://meta.discourse.org/t/watched-words-reference-guide/241735#p-1178196-flag-6) for details about how that works. # Watched Words with Discourse Chat Some Watched Word types also work in chat channels when [Discourse Chat](https://meta.discourse.org/t/discourse-chat/230881) is enabled. The compatibility of each type with chat is as follows: | Watched Word Type | Works in chat? | | --- | --- | | Block | ✅ | | Censor | ✅ | | Require Approval | ❌ | | Flag | ❌ | | Link | ✅ | | Replace | ✅ | | Tag | ❌ | | Silence | ❌ | These Watched Words apply to all messages in Chat, whether they are in a channel or direct message between users. > Last edited by @MarkDoerr 2026-05-14T04:05:45Z > > Last checked by @hugh 2025-08-01T01:56:59Z > > > **Check document** > > > > Perform check on document: --- _[View the full topic](https://meta.discourse.org/t/watched-words-reference-guide/241735)._