How do I use the hCaptcha plugin?
The hCaptcha plugin supports WordPress core and many plugins with forms automatically. You should select the supported forms on the hCaptcha Integrations settings page.
For non-standard cases, you can use the [hcaptcha] shortcode provided by the plugin.
For example, we support Contact Forms 7 automatically. However, sometimes a theme can modify the form. In this case, you can manually add the [cf7-hcaptcha] shortcode to the CF7 form.
To make hCaptcha work, the shortcode must be inside the
…
tag.
How do I migrate from reCAPTCHA or Turnstile?
Go to Settings → hCaptcha → Tools and use the Migration Wizard.
It scans your site for existing CAPTCHA providers, shows what can be migrated, and applies the changes in one click.
How do I use the new AI / Abilities features?
hCaptcha exposes selected security actions via the WordPress Abilities API for use with automation tools, WP-CLI, and AI agents, making it suitable for agencies managing multiple WordPress sites. Requires WordPress 6.9 or newer.
The typical workflow consists of two steps: inspect threats and block offenders.
** 1. Inspect recent threat activity **
You can request an aggregated threat snapshot for a given time window.
Using WP-CLI:
wp ability run hcaptcha/get-threat-snapshot --input='{"window":"55d"}' --user=admin
Using REST API (authenticated):
curl --globoff -u "USER:APP_PASSWORD" \ "https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/get-threat-snapshot/run?input[window]=55d"
The response includes: * overall metrics (total requests, failure rate) * confidence and top error vectors * breakdown by error type and form source * a list of top offenders (if present)
Example (simplified):
{ "metrics": { "total": 353, "failed": 215, "fail_rate": "0.61" }, "signals": { "confidence": "high", "top_vectors": ["empty", "spam"] }, "breakdown": { "errors": { "empty": 160, "spam": 16 }, "offenders": [ { "offender_id": "a1376a016c4156933c4d49b0bc56fa01", "type": "ip", "count": 2 } ] } }
** 2. Block abusive offenders **
If an offender appears suspicious, you can block it using its offender_id.
Using WP-CLI:
wp ability run hcaptcha/block-offenders \ --input='{"offender_ids":["a1376a016c4156933c4d49b0bc56fa01"]}' \ --user=admin
Using REST API (authenticated):
curl --globoff -u "USER:APP_PASSWORD" \ "https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/block-offenders/run?input[offender_ids][]=a1376a016c4156933c4d49b0bc56fa01"
Example response:
{ "blocked": ["a1376a016c4156933c4d49b0bc56fa01"], "effective_until": "2026-01-01T22:22:09Z" }
** What is offender_id? **
offender_id is a stable hash of the IP address.
Raw IP addresses are never exposed to automation clients or AI agents.
This allows privacy-safe analysis and blocking, while still enabling deterministic enforcement.
** Can AI agents use this automatically? **
Yes. You can point an AI agent to a WordPress site with Abilities enabled and instruct it to: * discover available abilities * collect threat statistics * decide whether activity looks abusive * block the most active offenders
Internally, the agent performs the same commands shown above ( wp ability list , get-threat-snapshot , block-offenders ).
** 3. Export plugin settings **
You can export current plugin settings as JSON (optionally including keys) for backup or migration.
Using WP-CLI:
wp ability run hcaptcha/export-settings --include_keys --user=admin
Using REST API (authenticated):
curl --globoff -u "USER:APP_PASSWORD" \ "https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/export-settings/run?input[include_keys]=1"
** 4. Import plugin settings **
Import settings from a JSON file path on the server. Use allow_keys to apply the keys block and dry_run to validate without saving.
Using WP-CLI:
wp ability run hcaptcha/import-settings --allow_keys --dry-run=false --user=igor --input_file=1.json
Using REST API (authenticated):
curl --globoff -u "USER:APP_PASSWORD" \ "https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/import-settings/run?input[input_file]=%2Fpath%2Fto%2Fhcaptcha-settings.json&input[allow_keys]=1&input[dry_run]=0" WP-CLI commands for exporting and importing settings
The plugin also adds the wp hcaptcha export and wp hcaptcha import commands.
Export settings
`
wp hcaptcha export –pretty > hcaptcha-settings.json wp hcaptcha export –include-keys –file=./hcaptcha-settings.json `
Parameters: * --include-keys — include the site_key and secret_key values. * --pretty — pretty-print JSON for readability. * --file=<path> — write JSON to a file instead of STDOUT.
Import settings
`
wp hcaptcha import ./hcaptcha-settings.json wp hcaptcha import ./hcaptcha-settings.json –dry-run wp hcaptcha import ./hcaptcha-settings.json –allow-keys `
Parameters: * --dry-run — validate the JSON without saving. * --allow-keys — allow importing keys from the keys block.
You don’t support plugin X. How can I get support for it added?
Open a PR on GitHub : or just email the authors of plugin X. Adding hCaptcha support is typically quite a quick task for most plugins.
Does the [hcaptcha] shortcode have arguments?
Full list of arguments:
[hcaptcha action="my_hcap_action" name="my_hcap_name" auto="true|false" ajax="true|false" force="true|false" theme="light|dark|auto" size="normal|compact|invisible" honeypot="true|false"]
The shortcode adds not only the hCaptcha div to the form but also a nonce field. You can set your own nonce action and name. For this, use arguments in the shortcode:
[hcaptcha action="my_hcap_action" name="my_hcap_name"]
and in the verification:
$result = \HCaptcha\Helpers\API::verify_post( 'my_hcap_name', 'my_hcap_action' );
For the explanation of the auto=”true|false” argument, see the section “How to automatically verify an arbitrary form” . By default, auto="false" .
The argument force=”true|false” allows forcing verification of hCaptcha widget before submitting the form. By default, force="false" .
The argument size=”normal|compact|invisible” allows setting the size of hCaptcha widget. By default, size="normal" .
The argument honeypot=”true|false” allows enabling or disabling the honeypot for the shortcode form. By default, it follows the global Honeypot setting.
How to add hCaptcha to an arbitrary form
First, add the hCaptcha snippet to the form.
If you create the form as an HTML block in the post content, insert the shortcode [hcaptcha] inside it. It may look like this:
<form method="post"> <input type="text" name="test_input"> <input type="submit" value="Send"> [hcaptcha] </form>
If you create the form programmatically, insert the following statement inside it:
?> <form method="post"> <input type="text" name="test_input"> <input type="submit" value="Send"> <?php echo do_shortcode( '[hcaptcha]' ); ?> </form> <?php
Secondly, verify the result of hCaptcha challenge.
$result = \HCaptcha\Helpers\API::verify_request(); if ( null !== $result ) { echo esc_html( $result ); // Block processing of the form. } How to automatically verify an arbitrary form
Arbitrary user forms can be verified easily. Just add auto="true" or auto="1" to the shortcode:
[hcaptcha auto="true"]
and insert this shortcode into your form.
Auto-verification works with forms sent by POST on frontend only. It works with forms in the post content and in widgets.
You can add also force="true" or force="1" argument to prevent sending a form without checking the hCaptcha.
[hcaptcha auto="true" force="true"]
Arbitrary forms can also be submitted via AJAX using the ajax argument. For backward compatibility, the shortcode enables automatic verification when ajax="true" is set and auto is omitted.
[hcaptcha ajax="true"]
If your code verifies the form itself, use [hcaptcha ajax="true" auto="false"] . The same applies to HCaptcha::form() in PHP: specify auto=false to use AJAX submission with your own verifier.
How to block hCaptcha entirely on a specific page?
hCaptcha starts early, so you cannot use standard WP functions to determine the page. For instance, to block it on my-account page, add the following code to your plugin’s (or mu-plugin’s) main file. This code won’t work being added to a theme’s functions.php file.
/** * Filter hCaptcha activation flag. * * @param bool|mixed $activate The activate flag. * * @return bool */ function my_hcap_activate( $activate ): bool { $status = (bool) $status; $url = isset( $_SERVER['REQUEST_URI'] ) ? filter_var( wp_unslash( $_SERVER['REQUEST_URI'] ), FILTER_SANITIZE_FULL_SPECIAL_CHARS ) : ''; if ( '/my-account/' === $url ) { return false; } return $activate; } add_filter( 'hcap_activate', 'my_hcap_activate' ); How do I block hCaptcha scripts everywhere except on a specific page?
As an example, to block hCaptcha scripts everywhere except on the contact page:
/** * Block inline styles. * * @return void */ function hcap_block_inline_styles() { if ( is_page( 'contact' ) ) { return; } $hcaptcha = hcaptcha(); remove_action( 'wp_head', [ $hcaptcha, 'print_inline_styles' ] ); remove_filter( 'wp_resource_hints', [ $hcaptcha, 'prefetch_hcaptcha_dns' ] ); } add_action( 'wp_head', 'hcap_block_inline_styles', 0 ); Skipping hCaptcha verification on a specific form
The plugin has a filter to skip adding and verifying hCaptcha on a specific form. The filter receives three parameters: current protection status (‘true’ by default), source, and form_id.
The source is the plugin’s slug (like ‘directory/main-plugin-file.php’), the theme name (like ‘Avada’) or the WordPress core (like ‘WordPress’).
The form_id is the form_id for plugins like Gravity Forms or WPForms, the post id for comments, or a general name of the form when the form does not have an id (like WordPress core login form).
Filter arguments for some plugins/forms are listed below.
Affiliates $source: ‘affiliates/affiliates.php’ $form_id: ‘login’ or ‘register’
Back In Stock Notifier $source: ‘back-in-stock-notifier-for-woocommerce/cwginstocknotifier.php’ $form_id: product_id
BBPress $source: ‘bbpress/bbpress.php’ $form_id: ‘new_topic’, ‘reply’, ‘login’, ‘register’ or ‘lost_password’
Beaver Builder $source: ‘bb-plugin/fl-builder.php’ $form
