WordPress

BytePhase Connector is a free plugin on the WordPress plugin directory. It sends form submissions from a WordPress site into BytePhase as leads or self check-ins. No code, no field mapping in WordPress — the plugin forwards the fields as the visitor typed them and BytePhase does the mapping.

For a step-by-step walkthrough with screenshots see bytephase.com/integrations/wordpress. This page covers how the plugin relates to the API.

Install

• From wp-admin: Plugins → Add New Plugin → search “BytePhase Connector” → Install → Activate.
• From the command line: wp plugin install bytephase-connector --activate.

Requires WordPress 6.0+ and PHP 8.1+.

Connect

1. In BytePhase, open Settings → Integrations and choose WordPress. The wizard’s Connect step creates the integration with the WordPress provider type and shows the three values the plugin needs: the API key (“Copy this key now. You will not be able to see it again.”), the BytePhase API address and your Store ID.
2. In WordPress, open BytePhase → Connection, paste those values exactly as shown, save, and click Test Connection. It should say “Connected to BytePhase.” Back in BytePhase, submit any form on your site once so its fields are detected, then finish the wizard and press Activate.

The plugin stores the key write-only: it is masked after saving, never shown again and never logged.

Use the WordPress provider type, never Zapier

BytePhase creates a WordPress-typed key for you when you follow the steps above; keep it that way. A WordPress-typed key can only create leads and self check-ins. The key lives in your WordPress database, where anyone with admin or database access to the site can read it. If the site is ever compromised, an intake-only key means junk leads — annoying, cleanable, not a data breach. A Zapier-typed key in the same place would let the intruder read your customers, leads, repairs and payments. See Authentication.

Add a form

The plugin supports:

Source	How it is identified	Mapping needed
Built-in form [bytephase_lead_form]	fixed	None — it already uses BytePhase’s field names
Built-in form [bytephase_self_checkin]	fixed	None — creates a self check-in, includes a serial-number field
Contact Form 7	the CF7 form id	Map once in BytePhase
Elementor Pro Forms	the form’s name — give each form a unique name and avoid renaming it	Map once in BytePhase
Any theme or plugin, via do_action('bytephase_submit_form', …)	the form_id you pass	Map once in BytePhase

The built-in shortcodes accept title and button attributes, for example [bytephase_lead_form title="Get a Free Repair Quote" button="Send Request"].

For Contact Form 7 and Elementor, the plugin’s BytePhase → Forms screen lets you choose whether each form becomes a Lead or a Self check-in.

Map the fields once

Submit the form once. In BytePhase, open the WordPress integration: the submission appears as received with the field names your form used. Map them to BytePhase’s fields — at minimum name and one of email / mobile_number — activate the form, and retry the parked submission. From then on every submission from that form is created automatically. Renaming or restyling the form in WordPress changes nothing as long as the field names stay the same. See Concepts → Form and field map.

What the plugin sends

One request per submission to the intake endpoint, authenticated with the X-API-Key header, with a body of the form:

{
  "provider": "wordpress",
  "form_id": "contact-us",
  "destination": "lead",
  "data": {
    "your-name": "Jordan Ellis",
    "your-phone": "4155550142",
    "your-message": "Screen flickers after boot"
  }
}

• form_id identifies the form for mapping and destination.
• destination is lead or self_checkin, set from the Forms screen or the shortcode; when omitted, the form’s configuration in BytePhase decides.
• data is the raw submitted fields, verbatim.

The plugin generates a unique Idempotency-Key for every submission and reuses it on retries, so a retry after a network failure never creates a second record. See Idempotency.

Delivery, retries and the Health screen

• Successful sends are logged and done.
• Temporary failures (429, 5xx, network) are queued and retried in the background by WP-Cron with increasing delays (roughly 1 minute → 5 → 30 → 2 hours → 6 hours, up to about six attempts). Make sure WP-Cron runs on your host.
• Submissions BytePhase rejected outright (401, 422) are held on the Health screen for a manual retry once you have fixed the key or the mapping.
• BytePhase → Health shows connection status, the 7-day success rate, the last submissions, and each one’s Request ID with a copy button. That id is the X-Request-Id BytePhase returned; quote it to support. The log keeps only operational data (time, status, request id) for up to 30 days, never the customer’s details.

Troubleshooting

Symptom	Cause
Test Connection fails with 401	Wrong key or Store ID. Copy both again from BytePhase.
422 on every submission	The form is not mapped, or the map does not point at name plus email/mobile_number. See Submissions & Troubleshooting.
Submissions stuck “pending”	WP-Cron is not running. Use a real cron job, or retry from the Health screen.
The visitor sees a blank page	WordPress has no active theme; not a plugin issue.

Rate limit

60 requests per minute for the WordPress integration’s key. A normal site never approaches it; a spam flood is queued by the plugin rather than forwarded in a burst. See Rate Limits.

Rotating the key

Rotating the key in BytePhase stops the old one immediately. Paste the new key into BytePhase → Connection in WordPress straight away; submissions in the meantime are queued and delivered once the new key is saved.