Gravity Forms Moderation - WordPress Plugin

How to Set Up Gravity Forms Moderation to Protect Forms from Toxic Submissions

Gravity Forms Moderation is not meant for standard anti-spam protection. It solves a different problem: filtering abusive, threatening, and toxic text submitted by real people through WordPress forms. In this guide, we will walk through where the moderation workflow lives, how to connect Perspective API, which settings to choose after installation, how to verify the outcome, and where the plugin works best alongside other Gravity Forms protection layers.

This guide is written for site owners, WordPress administrators, entry reviewers, and developers who already use Gravity Forms and want to protect support teams, moderators, HR staff, community managers, or editors working with user-generated content. Rather than repeating the product's marketing copy, we will follow a practical path: preparation, installation, API keys, toxicity threshold, word lists, form-specific settings, notifications, validation, troubleshooting, and limitations.

The key point: Moderation does not replace anti-spam tools, CAPTCHA, IP checks, your site's legal policy, or human judgment. It is an extra layer that evaluates the text fields in a submission and helps keep harmful content from being shown to people unless necessary. That means proper setup should begin not with maximum strictness, but with a clear policy: which forms are high-risk, which fields should be analyzed, what to do with borderline submissions, and who is responsible for manual review.

It is also important to consider the current status of Perspective API. The official Perspective developer page states that the service is scheduled to shut down after 2026 and that new access requests will no longer be accepted after February 2026. For new Gravity Forms Moderation deployments, you should first confirm that you already have active access to Perspective API and keep a migration plan ready for another text moderation tool.

What Problem the Plugin Solves and Where Its Limits Are

Gravity Forms already includes several ways to protect forms: a built-in honeypot, reCAPTCHA, Cloudflare Turnstile, Akismet, AbuseIPDB, entry limits, conditional logic on the submit button, and additional add-ons. All of these tools are useful, but they answer different questions. Is this a bot? Is the IP address suspicious? Does the submission look like spam? Was the form submitted too quickly? Gravity Forms Moderation asks a different question: could the text inside this submission be toxic to the person who has to read it?

This layer is especially useful anywhere users can write longer free-form text: a contact form, complaint form, review form, support request, order comment, community submission form, registration form with open text fields, publication submission form, or public event contact form. In these cases, a harmful submission can still be technically valid: the user entered a name, email, and message, passed CAPTCHA, and does not look like a bot. But the content can still be abusive, threatening, or inappropriate for your team.

Moderation uses Perspective API. The text fields from a submission are sent for analysis, the service returns scores for the selected attributes, and the plugin stores the overall Toxicity Score as the highest score among those selected attributes. If any selected attribute reaches the configured threshold, the submission is treated as toxic. The selected rule is then applied: send the entry to the Toxic Entries Box or delete it without saving.

The plugin's boundary is clear: it deals with textual toxicity, not overall site security. It does not determine whether a file is malicious, does not replace a WAF, does not verify user permissions, does not block SQL injection, does not analyze images, and does not settle disputes about whether content is acceptable. It also does not turn moderation into a legally precise decision. The score is probabilistic, so it should be used as a signal, not as a final verdict.

Practical rule: if a form is open to a broad audience and includes a long message field, Moderation can reduce the burden on your staff. If your main issue is large-scale bot spam, start by configuring honeypot, Akismet, reCAPTCHA, Turnstile, or AbuseIPDB, then add Moderation as a layer for toxic messages submitted by real people.

Who Gravity Forms Moderation Is a Good Fit For, and When Another Protection Layer Makes More Sense

Gravity Forms Moderation works well for sites where submissions are handled by a real person: customer support, sales, editorial teams, HR, nonprofits, educational projects, public blogs, private communities, event sites, or services that accept reviews. If someone on your team regularly has to read user-submitted text, a toxicity filter helps prevent harmful messages from being opened without warning.

The Toxic Entries Box mode is especially useful. It does more than tag an entry with a number. It separates potentially toxic records from the normal flow. In the toxic list, text field values are blurred, and an administrator must consciously reveal them. That detail matters: the plugin helps protect not only your database from junk, but also the person working with submissions.

The plugin may not be the best first choice if you do not have active access to Perspective API, if your forms contain little or no open text, if your main issue is automated bots, if your internal policy does not allow form content to be sent to an external analysis service, or if you need a full approval workflow with multiple roles, comments, deadlines, and routing. In the last case, Gravity Flow with an Approval Step is a closer fit, while Moderation can serve only as an initial signal.

For Russian-language sites, expectations should be more cautious. Perspective API supports multiple languages, and Gravity Forms displays available attributes dynamically, but the official documentation warns that not every category is equally available for every language. In practice, that means English-language forms may offer a wider attribute set, while other languages may have fewer filters available or behave differently. Before enabling it in production, always test real wording in your audience's language.

What to Check Before Installation and Connecting Perspective API

Preparation matters more here than with a typical add-on. You are not just connecting a WordPress plugin, but an external API that receives form text for scoring. Before installation, you should review the technical requirements, your Gravity Forms license, API access, data handling policy, and a fallback plan in case the external service changes.

The official Gravity Forms documentation lists the baseline requirements: the add-on must be installed, Gravity Forms must be version 2.7 or newer, and you need a Perspective API key. The product page also states that Moderation is included with Gravity Forms Elite and Nonprofit licenses. Do not plan a rollout on a site using a Basic or Pro license unless you are ready to upgrade or use another tool.

The second preparation area is access to Perspective API. The Gravity Forms documentation describes the process through Google Cloud: create a project, request access, enable the API, create a key, and add it under Forms - Settings - Moderation. But the current Perspective developer page states that the API is being retired after 2026, and new access requests are no longer accepted after February 2026. So a new site should not build a critical workflow entirely around this service without a backup plan.

The third area is key security. Gravity Forms documentation explicitly warns that if you restrict your Perspective API key in Google Cloud, you should not use HTTP referrer restrictions, because the plugin makes server-side requests without a referer header. IP address restrictions using your web server's IP are appropriate instead. This is a practical detail that often breaks the connection: the key appears to exist, but Gravity Forms shows an error instead of a green checkmark.

Quick Checklist Before Installation

• Make sure Gravity Forms is active and the version meets the add-on requirements.
• Confirm that your license includes access to the Moderation Add-On.
• Verify that you already have a valid Perspective API key or a legitimate way to use previously granted access.
• Decide which forms will be analyzed: every form on the site or only higher-risk forms with open text fields.
• Decide what to do with toxic entries: save them in a separate review area or delete them immediately.
• Review your site's privacy policy: user-submitted text will be sent to an external analysis service.
• Prepare a fallback in case Perspective API is shut down: manual review, Gravity Flow, GC OpenAI, Akismet, Turnstile, or another process that fits your policy.

Do not start with aggressive entry deletion. At the first stage, it is better to route questionable records to the Toxic Entries Box, collect a few real examples, evaluate false positives, and only then decide whether some entries can be deleted automatically.

Installing the Add-On and Verifying the Initial Connection

Installation works like other official Gravity Forms add-ons: install and activate the Moderation Add-On in WordPress, then open the Gravity Forms settings. The exact path in the admin panel is Forms - Settings - Moderation. If the Moderation tab does not appear, first confirm that the add-on is actually activated, not just uploaded to the plugin list.

Paste the key created in Google Cloud after enabling Perspective API into the Perspective API Key field. After saving the settings, Gravity Forms shows a key validation indicator. A green checkmark means the site was able to connect to the service and the key was accepted. A red indicator or no confirmation usually points to one of four causes: the key was copied incorrectly, the API is not enabled in the selected Google Cloud project, Perspective access was not granted for that project, or the key is restricted in the wrong way.

How to Safely Test the Key Without Real Submissions

After saving the key, do not immediately send dozens of test messages through a public form. First create a separate test form with a single Paragraph Text field, enable Moderation for it, and submit a few harmless control entries. The goal of the first test is not to "catch" toxic text, but to confirm that a normal entry is saved, does not receive a false toxic status, and does not interfere with notifications.

Then add a neutral internal marker word to Custom Toxic Words, something that is not an actual insult and would never appear in normal submissions, such as a technical test token. Submit the form with that marker. If the entry is sent to the Toxic Entries Box or processed using the selected action, you have verified the full WordPress - Gravity Forms - Moderation settings - entry action chain without using harmful text.

What to Do If the Tab or Checkmark Does Not Appear

If the Moderation tab is missing, check add-on activation and license access. If the tab is present but the key does not validate, review the Google Cloud project, Perspective API activation, and key restrictions. If you use IP restrictions, make sure you use the actual outbound IP of the web server, not your home IP and not the site's domain. If the site runs behind managed hosting, a CDN, or a reverse proxy, the outbound IP for server-side requests may differ from the public address you see in the browser.

Post-installation check: a normal test submission appears in Entries, a submission containing the control word from Custom Toxic Words is handled using the selected action, and the key settings show no red indicator.

Global Settings: Threshold, Attributes, Custom Words, and the Action for Toxic Entries

Global settings define the default behavior. They are useful as a baseline site profile: for example, moderate protection for all forms with long text and stricter settings for public forms that frequently attract hostile messages. But it is important to understand inheritance. Gravity Forms documentation warns that form-level settings inherit from global settings only until you save custom settings for an individual form. After that, the form no longer receives updates from the global defaults automatically.

The main setting is Toxicity Score Threshold. This is a number from 0 to 1. The lower the threshold, the stricter the filter: more submissions may be marked toxic. The higher the threshold, the looser the filter: only stronger cases will be flagged. The settings documentation lists the default value as 0.5, and for conditional logic you should include the leading zero, such as 0.5 rather than .5.

For the initial production period, a reasonable approach is to start by saving entries to the Toxic Entries Box with a threshold around the middle of the scale, then review real submissions. If the team sees too many borderline false positives, raise the threshold. If harmful messages still reach the regular queue, lower the threshold or add Custom Toxic Words for expressions that matter specifically to your community. Do not copy someone else's threshold without validating it against your own forms and audience language.

Filtering Attributes and Form Language

Gravity Forms shows the attributes available for analysis. Official materials list categories such as Toxicity, Severe Toxicity, Identity Attack, Insult, Profanity, and Threat. But attribute availability depends on Perspective API language support, and Gravity Forms separately warns that simply listing a category in the interface does not guarantee equal support for the site's language. For multilingual forms, you should test each language separately: one form in English, one in Russian, and one in your audience's local language if it differs.

You do not always need to enable everything. For a support contact form, Toxicity, Insult, and Threat are usually the most relevant. For a community with public discussions, Identity Attack may matter more. Profanity should be enabled deliberately: not every harsh word is a threat, and on some sites users may describe a frustrating issue emotionally without attacking the employee reading it. If you enable too many attributes with too low a threshold, the team will end up with too many questionable entries.

Custom Toxic Words as a Targeted Rule

Custom Toxic Words is a list of words that automatically mark an entry as toxic when matched. It is not a replacement for Perspective API, but a targeted rule for expressions your team definitely does not want to see in the regular stream. The recent Moderation Add-On changelog notes that form-level settings now allow custom words to be used without a Perspective API key, and that global custom words were also fixed. This matters during the transition period: if Perspective becomes unavailable, custom words may remain as a minimal local filter, but they do not understand context the way the model does.

The word list should stay short and manageable. Do not turn it into a massive dictionary: it becomes harder to review, the risk of false matches goes up, and some expressions are better handled through community rules and manual moderation. Store the list in a way that makes it clear to an administrator why a word was added, who added it, and when the rule should be reviewed.

Action: Toxic Entries Box or Delete the Entry

The Action for Toxic Entries setting determines what happens after a positive match. The Send to toxic box option saves the entry but removes it from the normal flow and places it in a separate section. The Delete the entry option removes the entry without saving it. For most sites, starting with the toxic box is safer because it gives you an audit trail, a chance to correct false positives, and a better view of what is really happening.

Deletion makes sense only where your site policy already allows those submissions to be discarded, your team can afford to lose borderline requests, and the form does not accept business-critical inquiries such as legal complaints, customer disputes, security reports, employee concerns, or medical or financial requests. If a form can contain an important but confrontational signal, it is better not to delete it automatically.

Form-Specific Settings: Where to Disable, Tighten, or Inherit Defaults

After configuring the global settings, go through each form that contains user-submitted text. In the form editor, the path usually looks like Settings - Moderation. There, you can keep the global rules, disable Moderation for a specific form, or define custom settings. This is one of the most important sections, because form-level settings are what turn the plugin from a general safeguard into a deliberate workflow.

Imagine a site with three forms: a short "Ask a Question" form, a longer "Leave a Review" form, and a private "Support Request" form for clients. If you apply the same threshold to all three, the outcome will be blunt. In the short form, most submissions are neutral and aggressive messages should be separated. In reviews, some emotional language may be acceptable because the user is describing a bad experience. In support, you cannot afford to lose an important issue even if the tone is sharp.

When to Keep Global Inheritance

Keep the defaults if the form is standard, does not accept critical information, and carries roughly the same risk profile as the rest of the site's forms. For example, several contact forms across different sections can easily share one profile: the same threshold, selected attributes, routing to the Toxic Entries Box, and the same notification behavior.

The main advantage of inheritance is easier maintenance. If you adjust the global threshold after a week of observation, every form without its own saved profile will get the new behavior. That is convenient on a small site where one team handles all submissions.

When to Create a Custom Profile

Custom settings are useful for forms with a distinct context. For an HR form, it is better to save questionable entries so you do not lose a potentially important application. For a complaints form, a softer threshold may make sense because users often write emotionally. For a public feedback form, a stricter profile may be appropriate if the team regularly receives harmful messages. For a private form used by authenticated clients, custom words and separate notification logic may be enough.

Once form-level settings are saved for the first time, that form no longer inherits future global changes. Keep a simple record of which forms use custom rules, why they differ, and when they should be reviewed. Without that list, a few months later it becomes difficult to understand why one form behaves differently from another.

When to Disable Moderation for a Form

Disabling it is reasonable if the form is purely technical and contains almost no user-written text: date pickers, a short email opt-in, a callback request without comments, an internal admin form, or a form where the data is not read directly by a person. You should also avoid enabling external analysis for fields containing sensitive information if your site policy does not allow that text to be sent to an external API.

The configuration should match the form's actual risk. The more free-form text and the broader the audience, the more value Moderation provides. The more sensitive data and legal implications are involved, the more carefully you should approach automatic deletion and external processing.

How Scoring Works: Form Fields, Selected Attributes, and the Toxicity Score

To troubleshoot plugin behavior correctly, you need to understand the scoring mechanics. When Moderation is enabled for a form, user inputs are encoded and sent to Perspective API. The API returns a score from 0 to 1 for each selected attribute. Gravity Forms calculates the overall Toxicity Score as the highest score among the selected attributes. If the overall score is equal to or above the threshold, the entry receives toxic status.

That means a single high-scoring attribute can determine the fate of the entire submission. For example, if Toxicity is below the threshold but Threat is above it, the entry will still be toxic. This approach is helpful for protecting your team, but it requires careful attribute selection. If you enable Profanity just because it is listed, some emotional but useful messages may end up in the toxic box. If you disable Threat, you may miss serious messages that should be handled according to your internal process.

Why the Score Should Not Be Read as an Exact Percentage of Danger

Perspective API returns the probability that a piece of text may be perceived in a certain way, not a legal classification and not a clinical assessment. Research and practical writeups on Perspective API often emphasize that the score is a model signal shaped by language, training data, context, and the selected attribute. So do not write internal rules like "0.7 means the submission is 70% dangerous." A better framing is: "a score above the threshold means the entry should move into a separate handling path."

This is especially important in Gravity Forms because a form may collect different kinds of text. The same word can carry different meaning in a complaint form, technical report, or review. On a public product page, a rude word may violate publishing rules, while in a support form it may simply describe a frustrating issue without targeting the employee reading it. Threshold settings should reflect that context.

How to Test Without Using Harmful Examples

You do not need to paste real insults into test submissions and send them to employees. To validate the workflow, use Custom Toxic Words with a neutral control token enabled temporarily only on a test form. To test Perspective itself, you can use a few safe phrases that describe tone without harmful details, and review genuinely problematic text only inside a restricted process with limited access.

Your minimum test set should answer three questions: does a neutral submission go through, does the control submission go to the toxic box, and does conditional logic trigger the notification or confirmation message. If all three checks pass, the baseline workflow is functioning.

Toxic Entries Box and Manual Moderation Without a Harmful Content Stream

The Toxic Entries Box is one of the most practical features in the product. When Send to toxic box is selected, the entry does not mix with regular submissions. A separate Toxic filter appears in the Entries list, and the text fields in toxic entries are blurred. To read the content, a user must click the eye icon in the entry detail view. This lowers the risk of accidental exposure to harmful text for staff who only handle normal submissions.

Manual moderation adds another layer of control. Gravity Forms documentation describes the ability to manually mark an entry as toxic or non-toxic from the entries list, through bulk actions, and in the detail view. One important nuance: changing the toxic/non-toxic status does not change the original toxicity score stored in the entry metadata and does not affect dependencies that use the score in conditional logic. Status and score are related, but they are not the same thing.

How to Build a Team Workflow

Do not give Toxic Entries Box access to everyone who processes forms. It is better to assign one or two moderators who are prepared to work with this material, understand the internal policy, and know when not to open a message unless necessary. In a small team, that might be the site owner or support lead. In a larger project, it could be a separate role with limited access to entries.

Document a simple procedure:

1. A regular operator works only with the normal Entries list and does not open the Toxic filter.
2. At defined intervals, a moderator reviews the toxic box, starting with metadata, score, and any fields that can be assessed without revealing the text.
3. If the entry is clearly a false positive, the moderator marks it as non-toxic and returns it to the regular workflow.
4. If the entry violates policy, it is archived, deleted, or escalated according to the internal procedure.
5. If the entry contains threats or legally significant information, the decision is made by the responsible staff member, not by the automated setting.

When Manual Tagging Is Better Than Deletion

Deletion may seem simpler, but it removes your feedback loop. Without saved entries, you do not know how many false positives there were, which words fire too often, which forms are being targeted, or whether the threshold should change. That is why the Toxic Entries Box is a better choice for the first few weeks. Deletion should be enabled only for forms where you are confident the submission does not need to be kept and does not create an obligation to respond.

Do not confuse the toxic box with a spam folder. Spam is usually tied to bots, IP reputation, Akismet, reCAPTCHA, or honeypot. The toxic box is tied to Moderation's text scoring. If a submission disappears from the regular flow, first check which mechanism flagged it rather than changing every setting at once.

Notifications, Confirmations, and Conditional Logic Based on Toxicity Score

Gravity Forms Moderation becomes especially useful when the score is used in conditional logic. The documentation states that Toxicity Score can be used for confirmations and notifications, and the changelog also notes support for feed conditional logic with the appropriate Gravity Forms version. This means you can do more than hide an entry. You can also change the form's response: show a standard confirmation to a normal user, send a questionable submission to a moderator, and prevent a toxic submission from reaching the shared mailbox.

Confirmations: What the User Should See

Do not show an aggressive message like "your submission is toxic" if that could provoke conflict or reveal internal rules. A neutral wording works better: the submission has been received for review, a response may take longer, and the message will be reviewed according to the site's policies. If deletion mode is enabled, the wording should still match your site's policy without teaching the user how to bypass the filter.

For conditional logic, always enter the score with a leading zero. Use values like 0.5, 0.7, and similar, not the shortened format without the zero. It is a small detail, but the official settings reference calls it out explicitly.

Notifications: Who Should Receive Toxic Entries

Standard notifications can remain in place for submissions below the threshold. For toxic entries, it is better to create a separate notification that goes to a moderator or dedicated mailbox. The email body does not need to include every field in full. If the goal is to shield the team from harmful text, the message can contain only the entry detail link, form name, entry ID, and score. That way the moderator decides when to open the text.

If a submission is marked as spam by other Gravity Forms tools, notifications and feeds are typically not processed. But toxic status is part of Moderation's own logic, so test your actual combination: Moderation plus Akismet, Moderation plus Turnstile, Moderation plus honeypot. You cannot assume every filter behaves the same way.

Feed Conditional Logic: When It Matters

If the form sends data to a CRM, email marketing tool, helpdesk, Slack, webhook, or workflow, toxic entries should not be pushed into the regular external stream without review. In newer versions, the Moderation Add-On changelog notes support for using toxicity score in feed conditional logic when paired with the required Gravity Forms version. A practical example: a normal submission goes to Help Scout or the CRM, while a toxic entry stays in Gravity Forms and is sent only to the moderator.

Outcome check: submit one neutral test entry and one control toxic entry. Confirm that the first reaches the standard notification, while the second does not go to the shared mailbox or trigger an unnecessary feed.

Practical Example: A Support Form with a Separate Path for Questionable Messages

Let's look at a concrete use case. The site has a support form with the fields Name, Email, Topic, Message, and an optional upload. The team wants normal requests to go to the main helpdesk, while messages containing toxic text should be routed to a separate review flow so first-line operators do not open them by accident.

Goal

The goal is to achieve three outcomes: normal messages go into the standard support workflow, potentially toxic entries go to the Toxic Entries Box, and only the moderator receives a notification about them. The submission should not be deleted automatically, because some confrontational messages may still contain legitimate customer issues.

Preparation

• Gravity Forms is installed and working.
• The Moderation Add-On is activated.
• The Perspective API key has been added and validated with a green checkmark, or Custom Toxic Words is being used for temporary testing.
• The support form is already published on a test page or isolated from indexing on staging.
• The team has a separate email address for moderation review.

Configuration Steps

1. Open Forms - the target form - Settings - Moderation.
2. Keep Moderation enabled for this form.
3. Start with a moderate Toxicity Score Threshold, not below the middle of the scale unless you already have enough historical data.
4. Select attributes that fit a support form: toxicity, insult, and threat are usually more important than profanity by itself.
5. In Action for Toxic Entries, choose Send to toxic box, not Delete the entry.
6. Add a temporary Custom Toxic Word to validate the workflow, then remove it or replace it with a real short internal list after testing.
7. Create a separate notification for the moderator mailbox with conditional logic: Toxicity Score greater than or equal to the selected threshold.
8. Add the opposite logic to the standard notification so toxic entries do not go to the first-line operator.
9. If the form sends data to an external helpdesk, configure feed conditional logic so questionable entries are not forwarded into the normal stream before review.

Verification

First submit a normal test message: it should appear in Entries, trigger the standard notification, and reach the helpdesk if the feed is enabled. Then submit a message containing the control word from Custom Toxic Words. It should appear in the Toxic filter or receive toxic status, and the notification should go only to the moderator. After testing, remove the temporary marker from custom words, otherwise any user who accidentally repeats it will be flagged incorrectly.

A Common Detail People Miss

If the form is embedded on a page with aggressive JavaScript optimization, caching, or security plugins, that can affect not only Moderation, but also honeypot, reCAPTCHA, Turnstile, and form submission overall. So test the full workflow on the page where the form is actually published, not only in preview mode. For Moderation, logs and entry notes are especially important because they help you determine which mechanism changed the submission status.

Using It Together with Akismet, Turnstile, reCAPTCHA, AbuseIPDB, and Honeypot

The best outcome usually comes not from one "main" filter, but from layered protection. Gravity Forms Moderation catches toxic text. Akismet works on spam signals and learns from submissions marked as spam or not spam. reCAPTCHA and Turnstile help distinguish automated behavior from real users. AbuseIPDB checks IP reputation, country blocklists, and domain blocklists. Honeypot catches simple bots through hidden fields, JavaScript version hashes, and submission speed checks.

If you combine these tools without a plan, troubleshooting becomes difficult. An operator will see that an entry is missing or that no notification was sent, but will not know why. Each layer needs its own role. Moderation should be responsible for textual toxicity, not for all site spam.

A Basic Setup for a Public Form

For a standard public contact form, start with the built-in honeypot and one anti-bot layer such as Turnstile or reCAPTCHA, if that fits your privacy policy. Then add Akismet or AbuseIPDB if the actual problem is junk submissions, suspicious IPs, or fake leads. Only after that should you enable Moderation on forms with longer message fields, so you can separate toxic text from technical spam.

This order is easier to maintain. If a sudden spike comes from bots, you check anti-bot logs and spam entries. If the problem is abusive messages from real users, you look at the toxic box and toxicity score. If legitimate entries disappear, you inspect entry notes, logs, and notification/feed conditions.

When to Add a Workflow Instead of Another Filter

If every questionable entry has to go through a formal review, approval, revision request, approval step, or assignment to a responsible person, Moderation alone is not enough. In that case, Gravity Flow or another approval process is a better fit. Moderation can provide the initial signal that "this entry should not be sent to everyone," but the next step should be handled through a workflow: who reviews it, who decides, who comments, what is sent to the submitter, and how the history is recorded.

Compatibility with Save and Continue and Partial Entries

Gravity Forms separately documents limitations for some anti-spam tools when used with Save and Continue and Partial Entries. Captchas may not validate in those intermediate states, honeypot has its own rules, and Partial Entries are stored before the final submission. For Moderation, that means you should not assume toxic text will be scored at every interim draft step. Test the final submit event itself and confirm which add-ons run in your specific form.

Safely Extending the Logic with a Documented Filter

Most sites do not need custom code for Gravity Forms Moderation. The threshold, attributes, custom words, toxic box, and conditional logic cover the main use cases. But a developer may need to add a small, predictable check on top of the existing score. The documentation provides the gform_moderation_score filter for that purpose, allowing you to run custom checks and modify the score before it is saved in the entry meta.

Below is a cautious custom adaptation based on the documented filter. It does not modify the WordPress core, Gravity Forms, or the add-on. The example shows the principle: if the analyzed text field contains a URL, you can raise the score so the entry is sent for review. This is not a universal recommendation for every site. It is suitable only for forms where links in user messages are prohibited by internal policy or are often used abusively.

add_filter( 'gform_moderation_score', function ( $score, $entry, $form, $fields_to_analyze ) {
    if ( empty( $fields_to_analyze ) ) {
        return $score;
    }

    foreach ( $fields_to_analyze as $field ) {
        if ( ! in_array( $field->get_input_type(), array( 'text', 'textarea' ), true ) ) {
            continue;
        }

        $value = $field->get_value_export( $entry );

        if ( empty( $value ) ) {
            continue;
        }

        if ( preg_match( '/\b(?:https?:\/\/|www\.)[^\s]+/i', $value ) ) {
            $score['fields'][ (string) $field->id ] = 1;
            $score['total'] = 1;
        }
    }

    return $score;
}, 10, 4 );

Where to place it: child theme functions.php, a custom functions plugin, or a trusted snippets plugin. A snippets plugin is safer because it lets you disable the code quickly. After adding it, test only one form: a message without a link should behave as before, while a message containing a test link should receive toxic status. Rollback is simple: disable the snippet and submit another test entry.

Do not use this code as a replacement for anti-spam protection. A URL in a message is not always harmful: a client may send a link to an error page, order, document, or screenshot. So this snippet is suitable only for forms where links in open text are genuinely prohibited. If you run a support form, it is usually better to allow links and validate them through separate security rules.

If you are unsure, do not add code. Use Custom Toxic Words, conditional logic, role-based review, and a dedicated moderation mailbox instead. Code extensions should stay small, reversible, and understandable to the next site administrator.

Verifying the Setup: What You Should See in the Admin Panel and Emails

Moderation verification should be treated as a separate phase, not a quick "the form submitted, so it must be working." The plugin has several output points: entry status, the Entries list, the Toxic filter, blurred text fields, notifications, confirmations, feeds, and the raw toxicity score. If you check only one of them, you can miss a problem somewhere else. For example, an entry may correctly land in the Toxic Entries Box but still send the full message to a first-line operator because the notification conditional logic is misconfigured.

Start validation on staging or on a private test page. Do not use real abusive messages, especially if they could reach email, CRM, or the helpdesk. For the first round, a temporary Custom Toxic Word with a neutral technical marker is enough. That gives you a controlled trigger, avoids unpleasant content in inboxes, and helps you see which mechanisms are active.

Control Submission Below the Threshold

Submit a normal message without links, questionable words, or long emotional phrasing. It should appear in the standard Entries list, stay out of the Toxic filter, send the standard notification, and show the default confirmation message. If it immediately lands in spam or toxic, do not start by changing Moderation. First open the entry notes and see which mechanism fired: honeypot, Akismet, reCAPTCHA, AbuseIPDB, custom validation, or Moderation.

Then inspect the entry detail view. If Moderation is active, you should know where to find the score and status even when the entry is not toxic. On larger sites, it is helpful to create a short internal screenshot for operators showing where the Toxic filter is, where the status appears, and where they should avoid clicking the eye icon unnecessarily. That is not a plugin setting, but part of the rollout process, and without it the team will get confused.

Control Submission Above the Threshold

Next, submit a message containing the temporary Custom Toxic Word. The expected outcome depends on the selected action. With Send to toxic box, the entry is saved and available through the Toxic filter. The text fields should be hidden or blurred until deliberately revealed. With Delete the entry, no record will remain, but that mode is not ideal for the first test because without the saved entry it is harder to see which part of the workflow fired.

Check notifications. If a separate moderation notification is configured, it should go only to the responsible mailbox and should not expose harmful text unless necessary. The toxic entry should not reach the standard mailbox unless you intentionally designed the process that way. If the form is connected to a CRM or helpdesk, confirm that the feed condition did not pass the toxic entry along the normal route.

Re-Testing After Changing the Threshold

You should not change the threshold "by feel" every time the team complains about a single entry. First collect several examples: what landed in toxic, what passed through, which attributes produced the highest score, and which words repeat. Then change only one parameter: the threshold, the selected attributes, or custom words. After the change, repeat the two control tests and one real-world validation using safe examples.

A good validation process does not end with "we don't see any errors," but with a clear outcome matrix: a normal submission goes to the standard operator, a questionable submission goes to the moderator, toxic text is not revealed accidentally, feeds do not send questionable content outward, and the administrator knows which layer flagged the entry. That matrix is especially important when Gravity Forms is connected to email, a CRM, webhooks, Slack, Help Scout, or an internal support queue.

Storage, Access, and Privacy: How to Deploy a Toxicity Filter Without Extra Risk

Moderation affects more than technical setup. It also affects how user data is handled. A form may contain names, email addresses, complaint text, order numbers, conflict descriptions, personal circumstances, and other information. If you enable external analysis without an internal policy, the problem can become organizational rather than technical. Before turning it on in production, decide which fields are sent for analysis, who can see toxic entries, and how long they should be stored.

Gravity Forms Moderation analyzes user inputs through Perspective API. The documentation describes this as secure passing of form inputs, but the site administrator still needs to understand that the text leaves the WordPress server for scoring. If the site operates in a regulated sector or accepts sensitive inquiries, review your privacy policy, client agreements, and internal data handling rules. In some cases, it is more appropriate not to analyze a certain form automatically and instead route it into a restricted manual review process.

Who Should Be Allowed to View the Toxic Entries Box

Access to toxic entries should be limited. Not every WordPress user who can process regular entries should be able to reveal blurred harmful text. In a small team, this can be handled organizationally: only the site owner or a senior staff member opens the Toxic filter. In a larger project, roles and capabilities should be configured so standard operators see only their normal workflow, while moderators have access to questionable records.

If Gravity Forms roles are already used across multiple departments, review them before enabling Moderation. A support form, HR form, and public review form may belong to different people. An access control mistake here is serious: a toxic message could be seen accidentally by someone who should not be handling that kind of content at all. That is why a Moderation rollout should be paired with a review of WordPress users rather than treated as just another checkbox in the add-on settings.

How Long to Keep Questionable Entries

There is no universal retention period. For ordinary spam-like messages, shorter retention may be enough. For complaints and conflict-related inquiries, longer retention may make sense if your internal process requires it. The main thing is not to let the toxic box turn into a permanent archive with no owner. If entries pile up for months, no one knows which ones are false positives, which require a response, and which should be deleted under the retention policy.

A practical workflow looks like this: the moderator reviews toxic entries regularly, returns false positives to the active workflow, deletes what does not need to be stored, and escalates important cases into a separate protected process. If an entry is revealed, that should also be a deliberate action. The built-in blur is helpful only if the team does not get into the habit of clicking the eye icon automatically.

What to Put in Your User-Facing Rules

You do not need to disclose the internal threshold, the custom word list, or the technical filtering setup. But it is useful to update your form usage rules: messages may be subject to automated and manual review, harmful or policy-violating text may be restricted in processing, and the team reserves the right not to respond to abusive submissions. The wording should be reviewed for both legal and editorial consistency with the site owner.

Privacy and safety matter more here than maximum automation. If you are not prepared to send form text to an external service, use local rules, manual review, Gravity Flow, or another approach instead. If you are prepared to do so, document it in your policy, limit access to toxic entries, and review the settings regularly, especially because Perspective API is scheduled for retirement.

Troubleshooting Errors and Unusual Moderation Behavior

Problems with Moderation usually show up as "submissions are not being flagged," "submissions disappear," "notifications are not arriving," "the key does not work," or "normal messages are ending up in toxic." Do not try to fix everything at once. First identify which layer made the decision: Moderation, spam protection, form validation, notification conditional logic, feed conditional logic, or an external service.

The Perspective API Key Does Not Validate

Symptom: there is no green checkmark in Forms - Settings - Moderation, or an error appears after saving the key. Possible causes: the API is not enabled in the Google Cloud project, Perspective access was not granted, the key was copied with a trailing space or cut off, the wrong project was selected, or the key is restricted by HTTP referrer even though the plugin needs server-side requests.

What to check: the Google Cloud project, whether Perspective API is enabled, whether the key is valid, and whether the server IP restrictions are correct. If your Perspective API access is new, take into account the current retirement notice and the end of new access requests after February 2026. If you do not have active access, do not try to build a critical workflow on an API that is not actually connected.

How to fix it: create or verify the key in the correct project, enable the API, replace HTTP referrer restrictions with IP address restrictions for the web server, and save the settings again. If the API is no longer available for your project, use custom words as a temporary local filter and plan an alternative.

Normal Messages End Up in the Toxic Entries Box

Symptom: staff members find useful submissions in the toxic box. Possible causes: the threshold is too low, too many broad attributes are enabled, custom words are creating false matches, the form language does not align with expected Perspective API support, or the user's text includes emotional wording without actually attacking a person.

What to check: the entry detail view, field-level scores, selected attributes, custom words, the submission language, and the form where it happened. If false positives mostly come from Profanity, try disabling that attribute or raising the threshold. If a custom word is triggering the flag, check whether it appears as part of an ordinary word or a technical description.

How to fix it: raise the threshold, narrow the attribute list, reduce the custom word list, keep send to toxic box instead of delete, collect several examples, and revise the rules. Roll back one change at a time, otherwise you will not know what helped.

Toxic Messages Pass Through as Normal

Symptom: the team receives harmful messages in the regular mailbox. Possible causes: Moderation is disabled on the specific form, form-level settings no longer inherit the global defaults, the threshold is too high, the necessary attribute is not selected, the message is written in a language or style Perspective handles less reliably, or the text is in a field that is not being analyzed.

What to check: form settings, whether Moderation is enabled, the attribute list, the threshold, the fields being analyzed, the entry meta, and logs. If the form was duplicated, do not assume the settings carried over correctly. Check the published form itself.

How to fix it: enable Moderation on the form, lower the threshold carefully, add the needed attribute, use custom words for recurring local expressions, and configure a dedicated notification rule. If the issue is systemic, add manual review for high-risk forms.

Notifications or Feeds Do Not Behave as Expected

Symptom: a toxic entry is sent to the shared mailbox, a normal submission does not reach the helpdesk, or different add-ons behave inconsistently. Possible causes: conditional logic is configured without a leading zero in the score, the condition is attached to the wrong notification, a spam layer marked the entry before feed processing, the form-level threshold differs from the global one, or feed conditional logic is available only with the required Gravity Forms version.

What to check: the conditions for each notification, the conditions for each feed, score formatting such as 0.5, entry notes, the spam folder, the Toxic filter, and version requirements in the changelog. For complex forms, run two tests: one with a neutral submission and one with a control toxic marker.

How to fix it: split notifications into a "regular" one and a "moderation review" one, enter the score with a leading zero, do not send toxic entries to an external helpdesk without review, and verify your Gravity Forms version if you rely on feed conditional logic based on score.

Entries Disappear and the Team Does Not Know Why

Symptom: a user says they submitted the form, but the entry is not visible in the regular list. Possible causes: Delete the entry is selected for toxic entries, honeypot aborts submission, reCAPTCHA or Turnstile validation failed, Akismet or AbuseIPDB marked the entry as spam, or form restrictions or validation blocked the submission.

What to check: the action for toxic entries, the spam folder, the toxic box, entry notes, Gravity Forms logs, and the settings for honeypot, reCAPTCHA, Turnstile, Akismet, AbuseIPDB, and form restrictions. If toxic entry deletion is enabled, the record may genuinely be gone.

How to fix it: during troubleshooting, switch Moderation to the Toxic Entries Box, and if possible and safe, configure honeypot and anti-spam layers to save spam entries instead of dropping them. Once you identify the cause, restore the stricter settings.

When Gravity Forms Moderation Is the Right Choice

Gravity Forms Moderation is worth using if your site already runs Gravity Forms, your forms accept open user-written text, your team regularly reads submissions, and there is a real risk of receiving insults, threats, or toxic messages. Its real strength is not "magically deleting the bad stuff," but creating a controlled buffer between the sender and the person handling the form.

A proper rollout looks like this: verify access to Perspective API and the service's current limitations, enable the add-on, validate the key, start with the Toxic Entries Box, choose sensible attributes, set a moderate threshold, configure form-level rules, separate moderator notifications, test both normal and control submissions, and then revise the threshold based on real data. If you are ready for that process, you can download the Gravity Forms Moderation archive and install the plugin in a test environment.

If your main pain point is bots, fake leads, suspicious IPs, or a formal approval process, do not start with Moderation. Use honeypot, Akismet, Turnstile, reCAPTCHA, AbuseIPDB, or Gravity Flow for their intended roles, and add Moderation only where you truly need to protect people from harmful text. That gives the site a system rather than a pile of random filters: a bot filter, spam filter, IP filter, text moderation layer, and human judgment for the cases where automation should not be trusted.