This guide explains how to configure and use Discourse AI’s spam detection feature, including the setup process, scanning criteria, classification logic, customizations, and contrasts with AI triage.
Required user level: Administrator
This is now default turned on for Starter and Pro customers, as well as our legacy Basic, Open Source, Creator, and Business customers.
Discourse AI provides an efficient spam detection feature that identifies and flags spam posts with minimal configuration. While designed for simplicity, it complements the more versatile AI triage system, which supports broader workflows and larger use cases.
Summary
In this guide, you will learn:
- How AI spam detection works and what content is scanned
- The classification logic and context used by the AI
- Steps to configure spam detection through
/admin/plugins/discourse-ai/ai-spam - Guidelines for Large Language Model (LLM) selection
- Key differences between spam detection and AI triage
- How to manage flagged and missed posts
How AI spam detection works
What content gets scanned?
AI spam detection evaluates posts based on these criteria:
-
User trust level:
- Scans posts from users at or below the configured maximum trust level (controlled by the
ai_spam_detection_max_trust_levelsite setting, default: trust level 1). - Excludes posts from higher trust levels.
- Always excludes posts from staff and bot users regardless of trust level.
- Scans posts from users at or below the configured maximum trust level (controlled by the
-
Post type:
- Public posts (excluding private messages).
- Both reply posts and first topic posts are included, based on additional thresholds.
-
Post edits:
- Scans posts with significant edits (e.g., changes exceeding 10 characters).
- Enforces a 10-minute delay between scans of the same post.
- Limits rescans to a maximum of 3 scans per post.
- Only rescans posts edited within the last 24 hours.
-
Post frequency:
- Scans posts from users with no more than the configured post count threshold (controlled by the
ai_spam_detection_max_post_countsite setting, default: 3 posts) in public topics. - Excludes posts from users exceeding this threshold.
- Scans posts from users with no more than the configured post count threshold (controlled by the
-
Review queue:
- Posts that were already approved from the review queue are not scanned.
The classification process
Posts that meet the criteria are sent to an AI agent for analysis. The agent evaluates whether the post is spam or not spam and provides a reason for its classification, using structured JSON output. The evaluation is based on:
- Context: Includes post content, topic title, category, user account data (e.g., username, email, account age, total posts, and trust level), and IP-based geo-location information.
- Image analysis: Up to 3 image uploads attached to a post are included for analysis.
- Reply context: For reply posts, the parent post content (up to 500 characters) is included.
- Site information: The site name, URL, description, and top 10 categories are provided to the AI.
- Custom instructions: Admin-defined rules for reinforced or adapted scanning criteria.
- Automated detection:
- Flags irrelevant or promotional content (e.g., ads or commercial materials).
- Identifies automated or bot-like behaviors.
- Assesses content relevance to the discussion.
Default prompt and context
The AI uses a default system prompt to guide spam detection. The built-in spam detection agent prompt covers:
You are a spam detection system. Analyze the following post content and context.
Consider the post type carefully:
- For REPLY posts: Check if the response is relevant and topical to the thread
- For NEW TOPIC posts: Check if it's a legitimate topic or spam promotion
A post is spam if it matches any of these criteria:
- Contains unsolicited commercial content or promotions
- Has suspicious or unrelated external links
- Shows patterns of automated/bot posting
- Contains irrelevant content or advertisements
- For replies: Completely unrelated to the discussion thread
- Uses excessive keywords or repetitive text patterns
- Shows suspicious formatting or character usage
Be especially strict with:
- Replies that ignore the previous conversation
- Posts containing multiple unrelated external links
- Generic responses that could be posted anywhere
Be fair to:
- New users making legitimate first contributions
- Non-native speakers making genuine efforts to participate
- Topic-relevant product mentions in appropriate contexts
The scanner also compiles a context package, including:
- Post type (NEW TOPIC or REPLY) with category and topic metadata.
- For replies: the parent post content and topic author.
- Author data (username, email, account age, total posts, trust level, and IP-based location).
- Post text truncated to 5000 characters for processing.
- Up to 3 image uploads attached to the post.
Configure AI spam detection
Configuration guide
-
Access settings:
Navigate to/admin/plugins/discourse-ai/ai-spam. -
Select an LLM:
If your site is hosted by Discourse
You can select our CDCK Hosted Small LLM from the LLM list.
- Choose a language model suited to your forum’s needs. See the Large Language Model (LLM) settings page for configuring LLMs.
- Access
/admin/plugins/discourse-ai/ai-llmsfor LLM configurations.
- Activate spam detection:
Enable spam detection by toggling the feature on.
-
Add customized instructions:
- Define rules specific to your forum (e.g., stricter monitoring of external links).
- Save any changes to apply them.
-
Adjust scanning thresholds (optional):
ai_spam_detection_max_trust_level: Set the maximum trust level of users whose posts are scanned (default: 1). Can be set from 0 to 4.ai_spam_detection_max_post_count: Set the maximum number of posts a user can have and still be scanned (default: 3). Can be set from 1 to 100.
Differences from AI triage
While spam detection is designed specifically for identifying spam, AI triage supports broader post management tasks.
| Feature | AI Spam Detection | AI Triage |
|---|---|---|
| Complexity | Streamlined, opinionated setup | Highly customizable and flexible |
| Primary use case | Detecting spam with minimal overhead | Advanced workflows for categorization, tagging, replies, spam detection, nsfw detection |
| Actions | Flags spam, hides posts, silences users | Tags, categorizes, hides posts, adds replies, flags posts, silences users |
| Recommendation | Easy setup and effective for most situations | Use for rich highly customizable workflows |
For more details, see Discourse AI - AI triage.
LLM selection recommendations
The performance of spam detection depends on the chosen LLM.
Most low-cost LLMs work effectively, such as:
- GPT-4o-mini
- Claude 3.5 Haiku
- Gemini 2.0 Flash
Experiment with different models to find the best fit. Configure your models via /admin/plugins/discourse-ai/ai-llms.
Testing spam scanner behavior
You can test spam detection rules directly from the configuration page.
- Paste a post URL or ID into the test field.
- Review the classification result and the AI’s reasoning for its decision.
- Unsaved changes are applied during testing, enabling experimentation without risk.
Managing flagged and missed posts
Handling flagged posts
When a post is detected as spam, the system:
- Flags the post as spam and adds it to the review queue.
- Silences the posting user.
- Hides the post from public view.
- Makes the topic invisible if the spam post was the first post in the topic.
Flagged posts appear in the moderation queue. Admins can:
- Approve legitimate posts wrongly classified as spam.
- Reject spam topics to keep the system accurate.
Important: Reject spam flags for incorrectly classified posts. Users remain silenced until the flag is resolved.
Handling missed spam
Missed spam refers to posts bypassing detection but flagged by the community. Moderators can manage these as necessary.
Best practices
- Monitor flagged and missed spam regularly to refine system accuracy. Clickable metrics simplify this process.
- Use test cases to evaluate custom instructions against edge cases.
- Review and adjust LLM settings when needed.
- Use the
ai_spam_detection_max_trust_levelandai_spam_detection_max_post_countsite settings to tune which users are scanned based on your community’s needs.
Additional resources
Configuring AI spam detection effectively reduces manual moderation efforts, ensuring a clean, spam-free community.
