=== HearBack — AI Calls Your Form Leads ===
Contributors: hearback
Tags: leads, forms, ai, phone calls, lead qualification
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

When a visitor submits a form with a phone number, an AI voice agent calls the lead within seconds, qualifies them, and emails your team a summary.

== Description ==

HearBack connects your WordPress forms to the HearBack calling service. The moment a lead submits a form on your site (with their express consent to be called), HearBack's AI voice assistant calls them back within seconds, asks your qualification questions, answers questions about your business, optionally books an appointment (Google Calendar or Cal.com), and emails your team a summary with a full transcript.

**How it works (v2):** you create a HearBack **account** in the portal at **https://app.hearback.in**, add your website there as an **App**, and paste the App API key into this plugin. Wallet, plan, phone numbers and domain verification all live in the portal — the plugin handles lead capture, the AI agent setup, form mapping and the call log inside wp-admin.

**Plans:**

* **Free** — 1 App (one website): outbound AI calls, transcripts, summaries, retries, calls placed from a shared HearBack number.
* **Pro** — multiple Apps plus per-site Pro features: calendar booking (Google Calendar or Cal.com), transfer-to-human mid-call, and AI inbound answering.

**Calling numbers:** buy a dedicated US or UK number in the portal for a stable caller ID of your own, or use the shared HearBack number at no monthly cost.

**Supported form plugins** (server-side hooks — no changes to your pages needed):

* Contact Form 7
* WPForms
* Gravity Forms
* Elementor Pro Forms
* Ninja Forms
* Fluent Forms

**What the plugin gives you in wp-admin:**

* A 4-step setup wizard: connect with your App API key, check your account/domain status, describe your business to the AI agent, and map your forms.
* Dashboard with wallet balance, plan, domain verification, number status and recent calls.
* Full call log with role-colored transcripts and extracted answers.
* Per-form mapping of phone and consent fields, with automatic detection.
* GDPR erasure tool and diagnostics.

**Consent is required.** HearBack refuses to call leads that did not tick a consent checkbox. The plugin detects acceptance/consent checkboxes automatically and the Forms screen includes copy-paste consent text and snippets.

**Domain verification is required for calls.** Each App verifies its domain with a DNS TXT record (shown in the portal). Calls stay blocked until the domain is verified — a safety measure so nobody can spend your wallet from a site you do not own.

= Important: this plugin relies on a paid third-party service =

HearBack is a connector for the HearBack SaaS. It does not place calls by itself. A HearBack account (created at https://app.hearback.in) and a prepaid wallet balance are required. Calls, phone-number rental and the Pro subscription are billed against your prepaid wallet by HearBack.

== External services ==

This plugin sends data to the HearBack API at **https://api.hearback.in** (operated by HearBack). Data is sent only after you connect the plugin with an App API key from the portal, and only for forms you enable.

**What is sent, and when:**

* On each enabled form submission: the submitted phone number, name and email (when present), all submitted field values, the page URL the form was submitted from, the visitor's IP address, the consent checkbox state and its label text, plus the form plugin/id/name.
* From admin screens: phone numbers you enter into the test-call and GDPR-erasure tools, agent configuration (business description, questions, notification emails, transfer number and, if you use Cal.com, your Cal.com API key — stored encrypted by HearBack, never on this site).

Account signup, wallet top-ups, plan changes, phone-number purchases and domain verification happen in the HearBack portal (https://app.hearback.in), not through this plugin.

This data is used to place and document the AI qualification call and to email summaries to the addresses you configure. Phone numbers of leads who opt out are stored on an opt-out list so they are not called again.

* Terms of Service: https://hearback.in/terms
* Privacy Policy: https://hearback.in/privacy

== Installation ==

1. Create your account at https://app.hearback.in, verify your email, and add this site as an **App** (use this site's exact URL). Copy the App API key.
2. Upload the plugin to `/wp-content/plugins/hearback` or install the ZIP via Plugins → Add New → Upload, then activate it.
3. Open the **HearBack** menu and follow the 4-step wizard: paste the App API key, review your status (domain verification, wallet, plan), configure your AI agent, then map your forms and place a test call.
4. Add the DNS TXT record shown in your portal to verify your domain — calls stay blocked until then.
5. Add a consent checkbox to each form (the Forms screen provides the text) — leads without consent are never called.

== Frequently Asked Questions ==

= Does this slow down my forms? =

No. Forwarding happens server-side with a 3-second timeout, and a failed forward is queued and retried in the background. The visitor's submission is never blocked or broken by HearBack.

= What happens if my site is cloned to staging? =

The plugin detects that the site URL changed and pauses forwarding so a staging clone cannot spend your wallet or call real leads. A notice with a one-click "Re-pair" button appears in wp-admin.

= Where is my App API key stored? =

In the WordPress options table, obfuscated with libsodium (keyed from your site's salts) when available, base64 otherwise. Treat database access as key access. You can rotate the key any time from the App page in the portal.

= I have a key starting with hb_live_ — why does it not work? =

That is a v1 key from the old in-plugin registration flow. Sign in at https://app.hearback.in, add your site as an App and use the new App key (starts with `hb_app_`).

= Do you call every form submission? =

No. Only enabled forms, only submissions that include a phone number, and only when the visitor ticked a consent checkbox. The service additionally enforces domain verification, opt-out lists, per-day velocity caps, deduplication, wallet state and quiet hours (8:00–21:00 in the lead's local time).

= Why are calls blocked? =

The most common reasons: your domain is not verified yet (add the DNS TXT record shown in the portal), your account is paused because the wallet dropped below $5 (top up in the portal), or the App is disabled. The Dashboard shows each of these states.

= How do I top up my wallet? =

In the HearBack portal (https://app.hearback.in) — the plugin links there wherever balance matters. Top-ups are bank transfers in multiples of $10 (minimum $30).

= How do I delete a lead's data (GDPR)? =

HearBack → Settings → "GDPR — erase a lead": enter the phone number and confirm. Personal data is erased from the service; billing ledger rows are kept with PII blanked.

= What does uninstalling remove? =

All plugin options (including the stored App API key) and the retry-queue table on this site. Your HearBack account, wallet, plan and phone numbers are not cancelled — manage those in the portal or contact support@hearback.in to close the account.

== Changelog ==

= 2.0.0 =
* Account → Apps model: accounts and Apps are created in the HearBack portal (app.hearback.in); the plugin now pairs by pasting the App API key (hb_app_…). In-plugin registration is gone.
* New 4-step wizard: Connect → Status check (domain verification, wallet, plan) → AI Agent → Forms & Test.
* Pro features in the agent form: calendar booking (Google Calendar or Cal.com), transfer-to-human, inbound answering — locked with an upgrade hint on the Free plan.
* Dashboard shows plan, domain verification and shared/dedicated number state, and a pause banner when the wallet drops below $5.
* Wallet, top-ups and phone-number purchases moved to the portal; the plugin links there.
* Form capture, adapters, retry queue, consent handling, staging-clone guard and GDPR tool are unchanged.

= 1.0.0 =
* Initial release: 5-step wizard, six form-plugin adapters, retry queue, calls log with transcripts, agent configuration, per-form mapping, staging-clone guard, GDPR tool.

== Upgrade Notice ==

= 2.0.0 =
HearBack v2: pairing now uses an App API key from the new portal at app.hearback.in. Old hb_live_ keys stop working — create an App in the portal and re-connect. Wallet and numbers are managed in the portal.

= 1.0.0 =
Initial release.
