AI Comment and Review Moderator documentation
A guide to AI Comment and Review Moderator: connecting your AI account, the dry run, how a comment is handled, thresholds, the local checks, the queue, the log and the statistics, privacy and limits.
Documents version 1.0.0Updated Oct 29, 2026
Start here
In plain words: AI Comment and Review Moderator checks every new comment and every WooCommerce product review. Cheap checks run on your site first (your allow-list and block-list, links, length, duplicates, a bot trap); only the comments that are still unclear are sent to your AI model, which gives scores from 0 to 100 for spam, abuse, off-topic, promotional links, personal data and, for reviews, signs of a fake or incentivised review, with short reasons. Your thresholds then decide: approve, hold for moderation, mark as spam, or leave it to the normal WordPress rules.
Important: The plugin never deletes and never trashes a comment. The worst it can do is mark one as spam, which you can undo in one click. It starts in dry run: it only scores and logs until you switch to Live.
Tip: It does not learn from your decisions and makes no promise of accuracy. AI can be wrong in both directions; keep an eye on the queue.
What you get
| Feature | What it does |
|---|---|
| Scores with reasons | Spam, abuse, off-topic, promotion, personal data and fake reviews, each 0-100, with up to three short reasons and a one-line summary. |
| Your thresholds | Per category: hold at, mark as spam at (0 = never). Spam wins over hold. Optionally approve comments whose scores are all low. |
| Checks on the site first | Allow-list (trusted roles, readers already approved by a person), blocked words and domains, too many links, too long, duplicates, a hidden bot trap, forum link codes: no AI call needed. |
| Never slows comments | Scoring runs in the background (Action Scheduler when WooCommerce is there, otherwise WP-Cron). The visitor never waits for the AI. |
| Waits safely | In Live mode a new comment can wait in moderation until it is scored. If the AI is down, too slow or the daily limit is reached, it follows the normal WordPress rules. |
| Moderation queue | Needs review, flagged, waiting, spam, errors; one-click and bulk approve, hold, spam or score again; the AI explanation of each comment. |
| Dry run first | The default after activation: everything is scored and logged, nothing changes. |
| Log and statistics | Every verdict with its source; counts per decision, who decided, disagreements with people, and a time estimate. |
| Injection hardening | The comment is sent as data between random markers; the answer is validated and can only contain known scores and labels; the decision is computed by the plugin. |
| Privacy | Only the comment text and minimal context are sent. Names, e-mail and IP addresses are never sent; links are made harmless; e-mail, phone and IP inside the text are masked. |
Requirements
| Item | Details |
|---|---|
| WordPress | 6.0 or newer |
| PHP | 7.4 or newer |
| Also | WooCommerce 8.0+ only if you want to check product reviews (optional) |
| An AI provider | An account and an API key with an OpenAI-compatible service (OpenAI, OpenRouter, Azure, a local server such as Ollama...) or with Anthropic. You pay your provider for what you use; the plugin has no usage fees. |
| License | GPL-2.0-or-later |
Install
- Unzip the package you downloaded. Inside is
ai-comment-and-review-moderator.zip(do not unzip this one). - In WordPress open Plugins → Add New Plugin → Upload Plugin, choose
ai-comment-and-review-moderator.zipand press Install Now. - Press Activate Plugin.
- Open Settings → AI Comment Moderator → AI connection, choose your provider, paste your API key and press Test the connection.
Connect your AI
In plain words: The plugin works with your own AI account. In Settings → (this plugin) → AI connection choose the provider, paste the key and press Test the connection: a green message tells you that the model answered.
| Field | Meaning |
|---|---|
| Provider | OpenAI-compatible (OpenAI, OpenRouter, Azure, Groq, Ollama, LM Studio...) or Anthropic. |
| API address | Leave empty for the official address. For another service enter it, for example http://localhost:11434/v1. |
| API key | Stored in your database (never shown again). You can define it in wp-config.php instead and the field disappears. |
| Model | The model name at your provider. A small, cheap model is enough for most tasks. |
| Maximum answer length | Caps the tokens of one answer, so a request cannot cost more than you expect. |
| Daily limit | The number of requests the plugin may make per day (0 = no limit). When it is reached the plugin stops asking until tomorrow. |
| Privacy | Hides e-mail addresses, phone numbers and card-like numbers before the text is sent. |
Tip: The table Recent use at the bottom of the tab shows the requests, the errors and the tokens of the last days.
Tip: A small, cheap model is enough. The daily limit is 200 requests by default: after that, comments simply follow the WordPress rules until tomorrow.
How a comment is handled
- A visitor sends a comment. While it is saved, the plugin runs its checks on the site only (no network call).
- Trusted commenters are left to WordPress. A local rule (blocked word, bot trap...) decides at once.
- Otherwise the comment is queued for the AI. In Live mode with Wait for the score it stays in moderation meanwhile (the moderators get no e-mail yet).
- In the background the AI scores it; the answer is checked; your thresholds give the decision.
- Approved, held (now the moderators get the usual e-mail) or marked as spam. If the AI fails, the comment gets the status WordPress gave it.
| Decision | Meaning |
|---|---|
| Approve | Only with Approve clean comments on, and never for a comment WordPress itself holds (your Discussion settings, moderation words, link limit). |
| Hold | Pending, waiting for a person. |
| Mark as spam | Moved to Spam; undo with Approve. |
| Leave to WordPress | The status WordPress gave the comment. |
Settings
In plain words: Settings → AI Comment Moderator. Start with Dry run, compare the log with your own decisions for a week or two, adjust the thresholds, then choose Live.
| Option | Meaning |
|---|---|
| Mode | Dry run (score and log only) or Live (apply the decisions). |
| What to check | Comments, product reviews or both. Pingbacks are never checked. |
| Wait for the score | Keep new comments in moderation until scored (Live mode). |
| Longest wait | After this many minutes a waiting comment follows the WordPress rules. |
| Approve clean comments | Approve when every score is at or below the value you set. Off by default. |
| Thresholds | Hold at / mark as spam at, per category. 0 = never. |
Allow-list, block-list and local checks
| Check | Result |
|---|---|
| Trusted roles | Comments of logged-in users with these roles are not checked. |
| Trusted readers | After N comments approved by a person, an e-mail address is trusted. Only a keyed hash is stored; marking a comment as spam removes the trust. |
| Blocked words and domains | Hold or spam (your choice), without an AI call. Domains match links and the website field, sub-domains included. |
| Bot trap | A hidden field (filled = spam) and a signed time (sent in under 3 seconds = hold). |
| Spam patterns | Forum link codes like [url=...] and comments that are only a link: spam. |
| Duplicates | The same text again within 24 hours: spam. |
| Links and length | More than 3 links or more than 3000 characters: hold without asking the AI. |
The moderation queue
In plain words: Comments → AI Moderation lists the comments the plugin checked. Each row shows the comment, the decision, the source (AI score, local check, allow-list), the score bars and buttons to Approve, Hold, mark as Spam or Score again. Open AI explanation for the reasons and the categories that reached your thresholds. Bulk actions do the same for many comments; there is no delete or trash action.
In plain words: WooCommerce lists product reviews on Products → Reviews, not on the Comments screen; the same AI moderation column is added there.
Log and statistics
In plain words: The Log keeps every verdict (no names, e-mail or IP addresses) for 90 days by default. Statistics counts the decisions of the last 30 days, who decided (allow-list, local checks, AI, errors, daily limit), the actions of people and the comments where a person chose differently from the plugin.
Important: The time estimate multiplies the comments approved or marked as spam without a person by the seconds you set. It is an estimate of time, not of quality.
Privacy and security
In plain words: Using an AI model means sending text to your provider. Only the comment text (links made harmless; e-mail addresses, phone numbers and IP addresses always masked), the title of the post or product, the type and, for reviews, the star rating and whether the buyer is verified are sent. The name, e-mail and IP address of the commenter are never sent. E-mail addresses, phone numbers and card-like numbers are masked first (an option, on by default). Nothing is sent to Taqnix. Mention your AI provider in your privacy policy: the plugin adds a suggested paragraph in Settings → Privacy.
Important: AI can be wrong. Treat what it writes as a draft and read it before you publish it.
| Risk | What the plugin does |
|---|---|
| A comment tries to give orders to the AI | The comment is wrapped as data between random markers; the instructions say it is untrusted; such attempts raise the spam score. |
| The AI answers something else | The answer must contain every score as a number 0-100 and one known label, or it is ignored and WordPress rules apply. Extra fields (for example "action") are dropped. |
| The AI decides | It cannot: the plugin computes the decision from the scores and your thresholds. |
| Costs | One AI call per unclear comment at most, a daily limit, short answers. |
| Who can act | Queue actions need the moderate_comments capability, the right to edit that comment and a security token. |
Arabic and right to left
Limits
| Limit | Detail |
|---|---|
| Accuracy | AI scores can be wrong. Use the dry run and check the queue, especially at first. |
| No learning | The plugin does not learn from your decisions; change the thresholds or the lists instead. |
| Low-traffic sites | WP-Cron runs on page visits; comments may wait a few minutes. A real cron job makes it faster. |
| Existing comments | Only new comments are checked; use Score again for single ones. |
| Not a replacement | Not a legal or compliance tool. It complements, and works next to, Akismet and your Discussion settings. |
For developers
In plain words: Skip this chapter if you only use the plugin.
// Score one comment now (normally done in the background); returns the verdict, a WP_Error or false
$verdict = TQCM_Moderator::process( $comment_id );
// The validated scores of a comment and the decision your thresholds give
$v = get_comment_meta( $comment_id, '_tqcm_verdict', true ); // source, decision, scores, label, reasons, summary...
$d = TQCM_Verdict::decide( $v['scores'] ); // array( 'decision' => approve|hold|spam|wp, 'because' => [...] )
// Add your own rules to the instructions (the comment stays data)
add_filter( 'tqcm_system_prompt', function ( $prompt, $is_review ) {
return $prompt . "\nOur shop sells garden furniture; questions about delivery are on topic.";
}, 10, 2 );
// Use WP-Cron even when Action Scheduler (WooCommerce) is there
add_filter( 'tqcm_use_action_scheduler', '__return_false' );
// The key can live in wp-config.php
define( 'TQCM_AI_KEY', 'sk-...' );Troubleshooting
| Problem | What to do |
|---|---|
| Comments stay on Waiting for the AI | WP-Cron has not run yet: visit the site, or call wp-cron.php from a real cron job. After the longest wait they follow WordPress rules. |
| AI errors in the queue | Test the connection in the AI connection tab; the key or model may be wrong. |
| Daily limit reached | Raise the daily limit, or let the local checks do more (block-list, links). |
| Too many comments held | Raise the hold thresholds of the categories that trigger most. |
| Nothing changes | You are in dry run: switch to Live in the settings. |
Updating and removing
Install the new zip over the old one in Plugins → Add New Plugin → Upload Plugin (WordPress offers to replace the current version), or replace the folder ai-comment-and-review-moderator by FTP. Your settings, the log and the verdicts are kept. Deactivating releases the comments that wait for a score. Deleting the plugin removes its settings, tables and comment data, never the comments. To remove the plugin, deactivate and delete it: its settings are removed with it.
Support
Installation help and bug fixes are included for 6 months, with lifetime updates. Contact us through the marketplace page where you bought the plugin or write to support@taqnix.com with your WordPress version, the plugin version and a screenshot.