# WordPress / Contact Form 7 + ShinrAI

Select form fields and attachments, then export protected content to your webhook. The plugin is GPL-2.0-or-later and free to install; ShinrAI service usage requires an API key. Direct ZIP installation is supported. Marketplace publication is pending.

## Install and connect

1. Install Contact Form 7, then upload `shinrai-cf7-0.1.0.zip` in **Plugins → Add New → Upload Plugin** and activate it. PHP 8.1+ with Sodium is required.
2. Open **Settings → ShinrAI**. Enter your ShinrAI API key, HTTPS destination and optional destination Bearer token. The destination is fixed administrator configuration.
3. Select the fields of each form you want to export. Enable attachment export and select the relevant file field if needed. Save settings.
4. Choose **Test connection**, then **Run protection example**. The example uses synthetic data and consumes a small amount of service allowance.
5. Submit a synthetic form and inspect both **Export queue** and your destination. A completed export shows **Delivered**. Keys are retained privately when their settings fields are left blank.

The plugin protects **configured webhook exports**. Contact Form 7's normal emails, local form storage, other plugins, search indexing and independent AI integrations retain their existing behavior. If you need email itself protected, configure your destination to send email from the protected export and disable the separate original-containing mail route in that form's own configuration.

## Export format and documents

The destination receives JSON with `submission_id`, `form_id`, `protected_text` and an `attachments` array. Each attachment has a generic filename, `content_type: application/pdf`, and `data_base64`. Original filenames, source paths, client IP addresses, user-agent metadata and restoration maps are excluded. The text combines selected field values with labels; it is not a field-for-field CRM payload. Map the protected text at your destination as appropriate.

TXT, PDF and DOCX inputs are supported, including supported scans and embedded images in English and German. Up to five attachments and 10 MB total input per submission; selected text is limited to 125,000 characters. Each document is subject to the service's 100-page, five-minute and 40-MB-output limits. PDF output is flattened. Invalid or incomplete processing fails the selected export; original attachments are never used as fallback. Your existing local handling remains separate.

## Reliable delivery

WordPress scheduled tasks process the queue. For quiet sites, run a system scheduler as your WordPress service account. For example, invoke `wp --path=/path/to/wordpress shinrai process --quiet` every 5–60 seconds. A step uploads, polls, downloads or delivers; the next invocation resumes saved progress. The supplied lab uses a dedicated scheduler container.

Form text also uses an idempotent document job. Upload retries and result downloads do not duplicate ShinrAI charges. The encrypted outbox survives application restarts. Destination delivery is **at least once**: a timeout after the destination accepted a request can cause a repeat. Your destination must deduplicate by the stable `Idempotency-Key` header or `submission_id`.

Transient connection, rate-limit and server errors retry with bounded backoff, up to eight attempts at a step. Invalid keys or unprocessable documents show a failure. Correct a key and use **Retry**; existing jobs require the same service/destination addresses. **Delete** removes a queued export when no step holds it. Successfully delivered payloads are erased immediately. Scheduled cleanup expires unfinished encrypted payloads after 24 hours and removes content-free status records after seven days. Cleanup resumes when the scheduler resumes after an outage. The queue holds at most 100 unfinished submissions.

Temporary content and saved credentials are encrypted with a key derived from WordPress authentication salts. Preserve those salts with your site's private recovery configuration. Changing them makes existing encrypted configuration and queued content unreadable. The remote service has its own encrypted retention and authenticated deletion.

## Troubleshooting and verification

Save before testing. `http_401`/`http_403`: check the key for the failing service. `http_429`: check allowance/rate limits. `connection_failed`: check reachability and scheduler progress. `document_protection_failed`: inspect format, OCR legibility and document limits. `queue_full`: resolve unfinished exports. `invalid_encrypted_state`: restore the original WordPress salts. Detailed errors intentionally omit customer content.

Reference versions are pinned in `lab.compose.yaml` and the QA handoff: WordPress 7.1, Contact Form 7 6.1.7 and PHP 8.3. Acceptance remains in progress until the QA report records the actual browser, attachment, retry and independent-installation checks. The lab-only HTTP allowlist and mail capture helper are not part of customer installation.

German guide: `README.de.md`. [Contact Form 7 data hooks](https://contactform7.com/2020/07/28/accessing-user-input-data/) and [file handling](https://contactform7.com/file-uploading-and-attachment/) define the source boundary.

## Validated example

The [screenshots](screenshots/) show the actual installed test application with synthetic data. Replacement values vary between runs. The download includes shared example documents and an executable connection test in `../fixtures/`.