WordPress Installation

Add Babel Shield to WordPress with automatic support for WPForms, Contact Form 7, and Gravity Forms.

Before You Begin

  • A Babel Shield account and API token -- see Getting Started
  • WordPress 5.0 or later

Supported Form Plugins

Plugin Detection AJAX Support
WPForms .wpforms-form Yes (AJAX forms detected via .wpforms-ajax-form)
Contact Form 7 .wpcf7-form Yes (always uses AJAX)
Gravity Forms .gform_wrapper form Yes (detected via gform_ajax hidden input)
Native Comments #commentform Standard form submit

Installation Methods

Theme Template (Recommended)

Add the script tag to your theme's header.php or footer.php before the closing </body>:

<?php // In footer.php, before </body> ?>
<script src="https://cdn.babelshield.ai/v1/babel-shield.js"
        data-api-token="YOUR_API_TOKEN">
</script>

wp_enqueue_script

Register the script in your theme's functions.php:

function my_theme_enqueue_babel_shield() {
  wp_enqueue_script(
    'babel-shield',
    'https://cdn.babelshield.ai/v1/babel-shield.js',
    array(), // No dependencies
    null,    // No version (CDN handles versioning)
    true     // Load in footer
  );
}
add_action('wp_enqueue_scripts', 'my_theme_enqueue_babel_shield');

Add the data-api-token attribute to the script tag:

function my_theme_babel_shield_attributes($tag, $handle) {
  if ($handle === 'babel-shield') {
    $tag = str_replace(' src', ' data-api-token="YOUR_API_TOKEN" src', $tag);
  }
  return $tag;
}
add_filter('script_loader_tag', 'my_theme_babel_shield_attributes', 10, 2);

Custom Plugin

Create a simple plugin to load Babel Shield:

<?php
/**
 * Plugin Name: Babel Shield
 * Description: AI-powered form content moderation
 */

function babel_shield_enqueue() {
  // Don't load on admin pages
  if (is_admin()) {
    return;
  }

  wp_enqueue_script(
    'babel-shield',
    'https://cdn.babelshield.ai/v1/babel-shield.js',
    array(),
    null,
    true
  );
}
add_action('wp_enqueue_scripts', 'babel_shield_enqueue');

function babel_shield_attributes($tag, $handle) {
  if ($handle === 'babel-shield') {
    $tag = str_replace(' src', ' data-api-token="YOUR_API_TOKEN" src', $tag);
  }
  return $tag;
}
add_filter('script_loader_tag', 'babel_shield_attributes', 10, 2);

What Gets Protected Automatically

Once loaded, Babel Shield detects WordPress and protects these form types:

  • WPForms forms (.wpforms-form)
  • Contact Form 7 forms (.wpcf7-form)
  • Gravity Forms (.gform_wrapper form)
  • Native comment forms (#commentform)

Only forms with user-generated text inputs are moderated. Forms containing only selects, checkboxes, or radio buttons are skipped.

What Gets Excluded Automatically

The adapter excludes forms that should not be moderated:

Excluded Form Reason
#loginform, #registerform, #lostpasswordform Authentication forms
form[action*="/wp-admin/"] Admin area forms
form.checkout, form.woocommerce-checkout Payment processing
.payment_box form, form#order_review Payment fields
form.woocommerce-cart-form Cart operations
form.search-form, form[role="search"] Search (not user content)

All forms on /wp-admin/* pages are skipped regardless of their action attribute.

WooCommerce Compatibility

WooCommerce checkout and payment forms are excluded using defense-in-depth: CSS selectors exclude known checkout classes, and a payment field heuristic detects credit card inputs (fields with cc- autocomplete attributes, card-number class, or payment_method names). This ensures payment forms are never moderated, even if a custom theme uses non-standard class names.

Gravity Forms Multi-Page Support

For multi-page Gravity Forms, only the final page submission is moderated. Page transitions (when gform_target_page_number is not 0) are skipped automatically. Users fill out multiple pages without moderation interruption -- content is checked when they click the final submit button.

AJAX Form Re-Submission

For AJAX forms (Contact Form 7, WPForms AJAX, Gravity Forms AJAX), Babel Shield intercepts the submit event, moderates the content, and then re-triggers the original submit button click to preserve the plugin's AJAX handlers. This is transparent -- no extra configuration needed.

Platform-Specific Troubleshooting

Forms Not Detected

Run BabelShield.diagnose() in the browser console. Check that adapter.name is wordpress and adapter.confidence is greater than 0.

If the adapter is not detected, verify the script loads after wp_head or in wp_footer. The window.wp global must be present when Babel Shield initializes.

WooCommerce Forms Being Moderated

This should not happen -- checkout forms are excluded by default. If it does occur, verify your checkout template uses standard WooCommerce classes (checkout, woocommerce-checkout). Custom checkout themes may need the data-babel-shield-ignore attribute.

Gravity Forms Moderating on Every Page

Verify the form has a gform_target_page_number hidden field. If missing, the Gravity Forms plugin may be misconfigured or using a non-standard template.

For API-level errors (rate limits, CORS, authentication), see Troubleshooting.

Next Steps