Developer hooks and WP-CLI for Contact Form 7

Formsieve for CF7 prefixes every hook with fsv_cf7_, bundles its own copy of the Formsieve core under the namespace Formsieve\CF7\Core\… and adds the WP-CLI command wp formsieve-cf7. The examples below are ready to paste into a small plugin or a must-use plugin (wp-content/mu-plugins/). Filters that run when a form is submitted also work from a theme's functions.php, but fsv_cf7_booted fires on plugins_loaded, before any theme is loaded, so a listener for it must live in a plugin or mu-plugin.

Filters

Actions

Context (Formsieve\CF7\Core\Pipeline\Context) gives you the submission as the integration built it: form_id(), fields(), email_domain(), message(), text(), settings(), setting( $key ), site() and more. It contains visitor data: never log or send it as a whole. Verdict (Formsieve\CF7\Core\Classifier\Verdict) offers verdict(), is_allow(), is_review(), is_block(), p(), spam_percent(), category(), reason(), reason_code(), stage(), model(), model_status(), provider(), request_id(), latency_ms(), input_tokens(), cost_micro_usd(), is_checked(), is_demo(), log_id() and with( array $changes ).

Examples

Skip one form entirely:

add_filter( 'fsv_cf7_should_check', function ( $check, $ctx ) {
	return 12 === $ctx->form_id() ? false : $check;
}, 10, 2 );

Stricter blocking on one form:

add_filter( 'fsv_cf7_thresholds', function ( $thresholds, $ctx ) {
	if ( 5 === $ctx->form_id() ) {
		$thresholds['block'] = 0.95;
	}
	return $thresholds;
}, 10, 2 );

Never block on one form; send its would-be blocks to review:

add_filter( 'fsv_cf7_verdict', function ( $verdict, $ctx ) {
	if ( 3 === $ctx->form_id() && $verdict->is_block() ) {
		return $verdict->with( array( 'verdict' => 'review' ) );
	}
	return $verdict;
}, 10, 2 );

Tell the model more about your site (keep visitor text out of everything except state.submission):

add_filter( 'fsv_cf7_payload', function ( $payload, $ctx ) {
	$payload['state']['site']['description'] .= ' We never buy SEO, marketing or web design services.';
	return $payload;
}, 10, 2 );

Changing the questions changes what the thresholds mean; see Calibration.

Log blocked submissions somewhere else:

add_action( 'fsv_cf7_decided', function ( $verdict, $ctx ) {
	if ( $verdict->is_block() && 'model' === $verdict->stage() ) {
		error_log( sprintf( 'Formsieve blocked form %d at %d%% (request %s)', $ctx->form_id(), $verdict->spam_percent(), $verdict->request_id() ) );
	}
}, 10, 2 );

Read the key from the environment:

add_filter( 'fsv_cf7_api_key', function ( $stored ) {
	$key = getenv( 'FORMSIEVE_KEY' );
	return $key ? $key : $stored;
} );

Add your own pre-filter stage (it runs first here). The class is declared only when Formsieve for CF7 is active, so the code cannot break the site when the plugin is deactivated:

add_action( 'plugins_loaded', function () {
	if ( ! interface_exists( 'Formsieve\CF7\Core\Pipeline\Stage' ) ) {
		return;
	}

	final class My_Partner_Allowlist implements \Formsieve\CF7\Core\Pipeline\Stage {
		public function id(): string {
			return 'partner_allowlist';
		}

		public function run( \Formsieve\CF7\Core\Pipeline\Context $ctx, \Formsieve\CF7\Core\Pipeline\Result $result ): void {
			if ( 'partner.example' === $ctx->email_domain() ) {
				$result->decided( 'allow', 'allowlist:partner' );
			}
		}
	}

	add_filter( 'fsv_cf7_pipeline_stages', function ( $stages ) {
		array_unshift( $stages, new My_Partner_Allowlist() );
		return $stages;
	} );
}, 30 );

WP-CLI

wp formsieve-cf7 test [<form_id>] [--sample=spam|ham] [--yes] [--format=table|json]
wp formsieve-cf7 stats [--days=<n>] [--format=table|json]

• test without a form ID sends the canned Test connection sample with the saved route and key (about 500 tokens) and prints the result; nothing is logged. Like the button, it sends nothing until consent is given for the saved route. It exits with an error when the connection fails, so you can use it in monitoring.
• test <form_id> builds a synthetic spam (default) or ham (--sample=ham) submission for that form and classifies it exactly like a real one: pre-filters, one API call (or Test mode), decision and one log row, marked as a WP-CLI sample (source = cli). Its API call counts in the API calls, tokens and cost, but the sample is not counted as a submission. Outside Test mode it spends one API call, so it needs --yes. The category field of its output is the raw category ID.
• stats prints decision counts per band, API share, tokens, cost, latency and corrections for the last --days days (default 30), plus the month to date and the projection, with the same rules as the dashboard: the decision counts cover visitor submissions only, while API calls, tokens and cost include re-checks and WP-CLI samples. --format=json adds the daily breakdown, categories and breaker state.

Data for developers

• Decision log: table {$wpdb->prefix}fsv_cf7_log. Numbers and identifiers only (times in UTC); read it, but do not write to it. The source column tells a visitor's submission (submission) from a WP-CLI sample (cli); only submission rows count as submissions on the dashboard. category holds the raw ID (for example vendor_solicitation); \Formsieve\CF7\Core\Admin\Format::category( $id ) returns the translated label the screens show. When a form uses do_not_store, or the visitor leaves a consent_for:storage box unticked, the row has no IP or e-mail hash.
• Options: fsv_cf7_settings, fsv_cf7_lists (the allow and block lists, not autoloaded), fsv_cf7_route, fsv_cf7_api_key (obfuscated, never read it directly) and more, all prefixed fsv_cf7_.
• During a submission, Formsieve pushes its result into Contact Form 7's submission as formsieve: WPCF7_Submission::get_instance()->pull( 'formsieve' ) returns the verdict, the outcome, the note and the subject tag (numbers, identifiers and Formsieve's own texts only).
• Flamingo messages: the Flamingo meta field formsieve holds the human-readable Formsieve note, for blocked, review-band and not-checked messages only (for every message when Notes is on); the post meta _fsv_cf7_verdict holds a summary array {log_id, form_id, verdict, percent, checked, demo, outcome} for every checked message.
• REST (both require manage_options and the wp_rest nonce):
  • POST /wp-json/formsieve-cf7/v1/test-connection backs the admin's Test connection button. It sends nothing until consent covers the tested route (error_code no_consent, sent: false), and it sends the saved key only to the saved route (no_key otherwise; type the key to test another route).
  • POST /wp-json/formsieve-cf7/v1/log/<id>/label with label = spam or ham records an administrator's correction for one log row, as the Log tab does.