# Lead capture (LD)

Research date: 13 November 2026. Anything not confirmed in the code or on a linked source is marked [unverified].

## Decisions (owner delegated, my recommendation, 2026-11-14)

1. **Design approved.**
2. **The generic webhook stays premium.** Leads exist in free (form, list, export, notification email); sending them on to other tools (webhook, HubSpot, Brevo, Mailchimp, Pipedrive) is the reason to upgrade.
3. **LD-11 (before-handoff trigger) comes after the customer centre track**, which adds the visitor-requested handoff it builds on.

## What exists today

- **No lead or contact model.** `app/Models` stores no email or name. New tables go into `app/Database/SchemaRegistry.php` (uninstall).
- **Only the admin assistant has a renderable that posts fields back.** `SecureSecretInput.jsx` (`adminRegistry.js`) dispatches a `callback` command with `args.values`; `useChatbotController.js` sends it through `POST /kimaai/v1/chatbot`, and `app/ChatBot/Tools/ToolCommandHandler.php` runs a `kimaai_chatbot_command_callbacks` callback and stores a fabricated answer via `AiService::saveChatResponse()`, which writes the payload to `kimaai_chats.input`. Wrong road for personal data [unverified whether `args.values` are stored; the design uses its own route].
- **Frontend renderables** (`defaultRegistry.js`): `product_list`, `gravity_form`, `form` (CF7), emitted by tool calls via `_kimaai_renderables` and `kimaai_chatbot_persisted_renderables`.
- **CF7 and Gravity Forms** (premium, `premium/app/Integrations/`) render the form plugin's HTML; CF7's REST endpoint or Gravity Forms' `submitForm` handles the submission. KimaAI only resets Turnstile on `wpcf7*` events. No link to the chat session.
- **Consent is client-side only**: `gdprConsent`, `gdprText` (`app/Admin/config/chatbot.php`, section `chatbotSecurity`) drive `GDPRConsentBox.jsx`, which writes `localStorage`. No server record.
- **No privacy exporters or erasers** anywhere.
- **Session**: cookie `kimaai_chatbot_session_id`, HttpOnly, SameSite Strict, 30 days (`app/Helper.php`). `kimaai_chats` stores per turn `user_id`, `ip` (blank for visitors), `session_id`, `input` JSON (`prompt`, `postId`, `lang`), `response` JSON, `created_at`; no secondary indexes.
- **Hooks**: `kimaai_chat_response_saved` (`AiService.php`:455), `ChatModel::countChatbotMessagesBySessionId()`, `kimaai_chatbot_handoff` from `premium/app/ChatBot/HumanHandoff.php` (its webhook is a blocking `wp_remote_post`, 10 s).
- **Infrastructure**: Action Scheduler bundled (`kimaai.php`:52). Public chatbot routes are `__return_true` with the cookie as ownership; REST nonce only for logged-in users (`ChatbotAssets.php`:201); `ChatbotRateLimiter` counts per HMAC of day and IP.

## Best practice in short

- **Chatbase "Collect leads"** is an action the agent calls when its "When to use" text matches (their examples: pricing, demo). Form mode has at most name, email and phone; conversational mode adds custom fields. Leads sit under Activity > Leads with CSV and PDF export, email notification per lead and a `leads.submit` webhook signed with HMAC-SHA1. [1, 2]
- **Chatbase Calendly and Cal.com actions** list open slots as text; no embedded widget. [3, 4]
- **HubSpot customer agent** (beta) qualifies against property-based criteria once the prospect shows interest, writes Qualified, Partially qualified or Not qualified to a property, and routes per status to a meeting link or a lifecycle change. [5] Intercom's Fin Sales Agent enriches the lead after it has the email, to ask fewer questions. [6]
- "Ask after the bot has helped, ask for few fields" is common practice without a primary source [unverified].
- **Calendly**: `Calendly.initInlineWidget({url, parentElement, prefill})` posts `calendly.event_scheduled` (event and invitee URIs only) to the parent; a plain iframe posts nothing. Webhooks reached the Free plan on 6 November 2026 per a staff post; the FAQ still says paid. [7, 8, 9]
- **Cal.com**: `Cal("inline", {elementOrSelector, calLink, config: {name, email}})` and `Cal("on", {action: "bookingSuccessfulV2"})`; loader and `init` details come from its snippet generator [unverified]. [10, 11, 12]
- **Upsert by email everywhere**: HubSpot `POST /crm/v3/objects/contacts/batch/upsert` with `idProperty: email` (Bearer token; new legacy private apps cannot be created since 26 October 2026, so the auth route needs checking at build time); Brevo `POST /v3/contacts` with `updateEnabled`, double opt-in through `/v3/contacts/doubleOptinConfirmation`; Mailchimp `PUT /3.0/lists/{id}/members/{md5(lowercase email)}` with `status_if_new: pending` for double opt-in; Pipedrive `POST /api/v2/persons`, then `POST /api/v1/leads`, which must link a person or organisation (token in the `x-api-token` header). [13 to 19]

## Design

### Data model

Migration `Version2026MMDDNN` creates two tables with `dbDelta(Model::createTableSql())`, as `Version2026012801` does; both models go into `SchemaRegistry`.

`LeadModel` (`kimaai_leads`): `id`, `session_id` VARCHAR(64), `user_id`, `status` VARCHAR(16) (`new`, `dismissed`, `erased`), `email` VARCHAR(190) NULL, `name`, `phone`, `company` VARCHAR(190) NULL, `fields` LONGTEXT JSON (extra configured fields), `trigger_type` VARCHAR(16) (`messages`, `intent`, `handoff`, `action`), `post_id`, `consent_text` TEXT, `consent_at` DATETIME, `marketing_opt_in` TINYINT, `score` SMALLINT NULL, `score_reasons` TEXT NULL, `created_at`, `updated_at`. Indexes: `UNIQUE (session_id)`, `KEY (email)`, `KEY (created_at)`. A dismissal is a row with `status = dismissed` and no personal data, so the trigger never asks twice and the lead step's take-up rate can be measured.

`LeadSyncModel` (`kimaai_lead_sync`, premium use, free schema): `id`, `lead_id`, `destination` VARCHAR(32), `status` (`pending`, `done`, `failed`), `attempts`, `remote_id`, `last_error`, `updated_at`; `UNIQUE (lead_id, destination)`.

### Lead step in the conversation

- New renderable `lead_form` in `defaultRegistry.js`: configured fields, a required processing consent checkbox with the admin's text, an optional separate marketing checkbox (never pre-ticked), a honeypot, "Not now".
- It submits to its own route `POST /kimaai/v1/chatbot/lead`, not the chat command path, so the values never reach `kimaai_chats` or the model. The route checks: session cookie present with at least one stored turn, `is_email`, consent ticked, honeypot empty, rate limit (5 per day per HMAC'd IP, reusing `ChatbotRateLimitModel` with its own key prefix), and `X-WP-Nonce` for logged-in users. One lead per session (upsert).
- The model gets at most a note that details were left, never the values.

### Triggers (setting `leadTriggers`)

- **After N visitor messages** (default 3): on `kimaai_chat_response_saved`, if the session's count equals N and the session has no lead row, append a `lead_form` renderable through `kimaai_chatbot_persisted_renderables`.
- **Buying intent**: a tool `offer_contact_form` in `kimaai_tools_registry` whose description tells the model to call it for pricing, quotes, demos or "contact sales". No extra classifier call.
- **Before handoff** (premium, as handoff is): `HumanHandoff::escalate()` asks for contact details first when the session has no lead, and adds the lead's email to the email and webhook it sends.

#### Built in LD-11

`premium/app/ChatBot/VisitorHandoff.php` checks before handing over, for the `request_human` tool and the "Talk to a person" button: with `handoff` in `leadTriggers` (offered on premium sites only), lead capture on, no lead row for the session (sent or declined) and no earlier handoff, the button answers with the `lead_form` renderable (trigger `handoff`) and the tool tells the model the form shows under its answer. Hydration adds a `command` to that form, the `request_human` callback, which the widget sends once the details are saved or "Not now" is recorded; the handoff then runs as built in CC. A logged-in customer whose handoff opens a helpdesk ticket gets no form: the ticket carries their account. `HumanHandoff` puts `Visitor email:` above the email body and `lead_email` (null without a sent lead) into the webhook body. Handoffs from negative feedback or an ungrounded answer do not ask: no visitor is waiting for them.

### Admin

Submenu "Leads" next to "Feedback Analytics" in `app/Admin/AdminInit.php`, React app in `src/admin/leads` on the design system primitives (track UI). REST `GET /kimaai/v1/leads` (paged, search, date and status filters), `DELETE /leads/{id}`, a transcript link to the session; CSV export through `admin-post.php` with a nonce, streamed in chunks, cells starting with `=`, `+`, `-` or `@` prefixed with `'`. Capability `manage_options`, filterable via `kimaai_leads_capability`. Optional notification email per lead.

### Settings

Section `leads` in `app/Admin/config/chatbot.php`, same schema style (`section`, `type`, `default`, `component`, `props`, `condition`, `onlyPremium`): `leadsEnabled`, `leadFields` (repeatable: key, label, type, required), `leadConsentText` (`translate => true`), `leadMarketingText`, `leadTriggers`, `leadAfterMessages`, `leadNotifyEmail`, `leadRetention` (presets as `ChatbotSessionRetention`). CRM and booking credentials go in `app/Admin/config/integrations.php`, one block per destination, `type => password` for tokens.

### CRM sync (premium)

`premium/app/Leads/Destinations/*` implement `LeadDestination` (`key()`, `isConfigured()`, `push(array $lead, string $remote_id): SyncResult`). On save, one `as_enqueue_async_action('kimaai_lead_sync', [lead_id, destination], 'kimaai_leads')` per enabled destination, skipped while `as_has_scheduled_action()` finds one for the same lead and destination. Action Scheduler's `$unique` flag compares only hook and group, not the arguments, so it would hold back the jobs of other leads [21]. Retries 1 min, 5 min, 30 min, 2 h, 12 h on 429 (honour `Retry-After`) and 5xx; 4xx other than 429 fails at once with the error shown in the list. All calls through `wp_remote_request` (Plugin Check, QA-8).

- HubSpot: upsert by email; which app type issues the token after the private-app change is settled in LD-8.
- Brevo and Mailchimp: contact upsert always; list subscription only with `marketing_opt_in`, Mailchimp `pending` (double opt-in) by default. Mailchimp's host from the data centre suffix of the key [unverified in the current docs, test with a real key].
- Pipedrive: find or create the person, then a lead linked to it.
- Webhook: JSON `POST` with `X-KimaAI-Timestamp` and `X-KimaAI-Signature: sha256=HMAC(secret, timestamp.body)`.

Payload: email, name, phone, company, extra fields, consent flags and time, trigger, page URL, score, a link to the transcript in WordPress. No transcript text by default.

#### Webhook format (built in LD-7)

Settings > Integrations > Lead webhook: URL and signing secret (a password field, blanked in the settings export). Every request is a `POST` with `Content-Type: application/json` and these headers:

| Header               | Value                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `X-KimaAI-Event`     | `lead.saved` (new or updated lead) or `lead.erased` (Tools > Erase Personal Data)                    |
| `X-KimaAI-Timestamp` | Unix time of the request, in seconds                                                                 |
| `X-KimaAI-Signature` | `sha256=` followed by the hex HMAC-SHA256 of `<timestamp>.<raw body>`, keyed with the signing secret |

Body of `lead.saved`: `{"event", "site", "lead": {"id", "email", "name", "phone", "company", "fields", "consent_text", "consent_at", "marketing_opt_in", "trigger", "page_url", "score", "score_reasons", "meeting_booked_at", "session_id", "leads_url", "created_at"}}`, times in ISO 8601 with the site's offset. `lead.erased` sends only `{"lead": {"id"}}`. `leads_url` opens the Leads page, not one transcript: the page has no link to a single lead yet.

A 2xx answer counts as delivered; network errors, 429 (with `Retry-After`) and 5xx are tried again after 1 min, 5 min, 30 min, 2 h and 12 h; any other status fails at once and the Leads page shows the error. A receiver checks the signature over the raw body, before parsing it, and rejects old timestamps:

```php
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_KIMAAI_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (!hash_equals($expected, $_SERVER['HTTP_X_KIMAAI_SIGNATURE'] ?? '') || abs(time() - (int) $timestamp) > 300) {
  http_response_code(401);
  exit;
}
```

```js
// Node.js, with the raw body as a Buffer (for example express.raw({type: 'application/json'})).
const crypto = require('crypto');
const timestamp = req.get('X-KimaAI-Timestamp');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${req.body}`).digest('hex');
const given = req.get('X-KimaAI-Signature') || '';
const valid = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
```

#### HubSpot (built in LD-8)

Settings > Integrations > HubSpot: an access token (password field, blanked in the settings export). Each lead is one `POST /crm/v3/objects/contacts/batch/upsert` with `idProperty: email` and `Authorization: Bearer <token>`; `email`, `firstname`, `lastname` (the name split at the first space), `phone` and `company` are sent only when not empty, so a lead never clears a contact's values. The contact ID is stored as the remote ID. A 207 answer without a result fails with HubSpot's message. Marketing consent is not written: HubSpot keeps it in subscription types, which need their own API.

Token: a private app with the `crm.objects.contacts.write` scope. Whether a new portal still gets a legacy private app after 26 October 2026, or needs a project-based app with a static token, is [unverified]; both send a Bearer token.

Manual smoke test with a HubSpot test portal (developer account > Test accounts):

1. In the test portal, create a private app with the scope `crm.objects.contacts.write` and copy its token.
2. On a premium site, turn on lead capture, then Settings > Integrations > HubSpot: enable, paste the token, save.
3. In the chatbot, leave a lead with a new email address, a full name, a phone number and a company.
4. Run the queue (Tools > Scheduled Actions, group `kimaai_leads`, or `wp action-scheduler run --group=kimaai_leads`).
5. KimaAI > Leads shows "HubSpot: sent"; HubSpot > Contacts has the contact with first and last name, phone and company.
6. Leave a second lead with the same email and a new company: the same contact is updated, no duplicate.
7. Replace the token with `invalid` and leave a lead: the list shows "HubSpot: failed" with HTTP 401 in the tooltip.

#### Brevo and Mailchimp (built in LD-9)

- **Brevo**: `POST /v3/contacts` with the `api-key` header, `updateEnabled: true` and `FIRSTNAME`, `LASTNAME` when given. `listIds` holds the configured list only when the lead agreed to marketing; without it the lead is a contact on no list. Phone and company are not sent: `SMS` must be in international format and `COMPANY` is not a default attribute, so either could make Brevo refuse the whole contact.
- **Mailchimp**: `PUT /3.0/lists/{audience}/members/{md5(lowercase email)}` on the data centre from the key's suffix, with HTTP Basic authentication and `FNAME`, `LNAME` when given. `status_if_new` is `transactional` without marketing consent, and `pending` with it (double opt-in, the default) or `subscribed` when the site turned double opt-in off. A member who already exists keeps their status, so a transactional contact who agrees later is not subscribed by KimaAI. That `transactional` is accepted in `status_if_new` is [unverified]: test with a real audience.

#### Pipedrive (built in LD-10)

API token in the `x-api-token` header on `https://api.pipedrive.com`. `GET /api/v2/persons/search` with `fields=email` and `exact_match=true` finds the person; without a match `POST /api/v2/persons` creates one with the name (or the email when no name was given), email and phone. Then `POST /api/v1/leads` adds a lead titled "Chatbot lead: name" and linked to the person. The remote ID is `person/lead`: a lead already in Pipedrive is not added again, and when only the lead step failed, the next attempt reuses the person. The company is not sent: it would need an organisation.

### Meeting booking (premium)

Renderable `meeting_booking` with `provider` (`calendly`, `calcom`) and a URL whose host must match the configured one. Click to load: the third-party script loads only after "Show calendar". Name and email prefilled from the lead form state in the browser. The `calendly.event_scheduled` or Cal.com `bookingSuccessfulV2` event posts `{event: 'meeting_booked'}` to the lead route, which raises the score; a browser signal, labelled as such; verified bookings through provider webhooks come later. Unlike Chatbase, KimaAI embeds the real widget, so the site holds no calendar API keys. Triggered by a tool `offer_meeting` and a quick action.

#### Built in LD-12

Settings > Integrations > Meeting booking: provider and booking page URL, which must be `https` on `calendly.com`, or `cal.com` or `app.cal.com`. The answer stores only `{"type": "meeting_booking"}`; hydration adds the page and the name and email of the session's lead, and drops the widget while booking is off. In the browser, the details sent in the lead form during the visit win. Nothing loads from the provider until "Show calendar": Calendly through `widget.js` and `initInlineWidget`, Cal.com through the queue loader of `embed.js` with `init`, `inline` and `on` (the loader details stay [unverified] until tested with a real Cal.com page). A booking posts `action: meeting_booked` to the lead route, which sets `kimaai_leads.meeting_booked_at` once, on the session's lead only, and fires `kimaai_lead_event`; the sync queue sends the lead again. The column was added to the LD-2 table definition, as the track is not released. The quick action trigger is not built.

### Lead score (premium)

Deterministic and explainable, 0 to 100, stored with reasons: business email domain (not on a free-mail list) +20, intent trigger +20, meeting booked +30, three or more visitor messages +10, phone given +10, visited a page the admin marks as high intent (pricing, contact) +10. Recomputed on each lead event, sent to CRMs as a property (HubSpot needs a custom contact property, created by the admin [unverified whether we create it via API]).

#### Built in LD-13

`premium/app/Leads/LeadScorer.php` scores on `kimaai_lead_saved` and `kimaai_lead_event` (priority 5, before the sync queue) and stores `score` with `score_reasons` as `[{"rule", "points"}]`. Rules: `business_email` 20 (domain not on the free-mail list, filter `kimaai_lead_free_mail_domains`; Yahoo, GMX, Hotmail, Outlook, Live and Yandex are matched in every country), `buying_intent` 20, `meeting_booked` 30, `engaged` 10 (three or more stored turns), `phone` 10, `high_intent_page` 10 (the lead's page or a page of the conversation is listed under Chatbot > Settings > Lead capture > High-intent pages, matched by URL path). The Leads page shows the score with its reasons. The webhook always sends it; each CRM only when the site names the field it created: HubSpot contact property, Brevo attribute, Mailchimp merge tag, Pipedrive person field key (sent on creation, later with `PATCH /api/v2/persons/{id}`). KimaAI does not create these fields through the APIs.

### Privacy

- Consent text and time stored with the lead; marketing consent separate.
- `wp_privacy_personal_data_exporters` and `_erasers` by email [20]: lead rows plus the chats, feedback and CSAT of the linked session. Erasure does not reach CRMs; the admin page says so and the webhook sends a `lead.erased` event.
- Retention job on the `ChatbotSessionRetention` pattern; suggested privacy policy text via `wp_add_privacy_policy_content()`.
- Nothing from the form goes to the AI provider.

### Free and premium

Free: lead form, triggers after N messages and buying intent, consent, leads list, CSV export, notification email, privacy tools, retention. Premium: before-handoff trigger, CRM sync, webhook, meeting booking, lead score.

### Tests

- PHPUnit unit with fakes: route checks, trigger rules, each destination against `pre_http_request` (URL, headers, body, retry mapping), signature, exporter, eraser, CSV escaping.
- Jest: `LeadForm` (consent unticked blocks submit, dismiss), `MeetingBooking` (no script before click, booking event).
- Playwright in WordPress Playground, chat stubbed with `page.route` as in `chatbot-widget.spec.ts`: form after N messages, submit, row in Leads, CSV download.

## Items

| Item | Title | Acceptance criteria |
| ---- | ----- | ------------------- |
| LD-2 | Lead tables, models and migration | Two tables created on fresh install and upgrade; in `SchemaRegistry`, dropped on uninstall; unit test for `createTableSql` |
| LD-3 | Lead form renderable and submit route | Values stored only in `kimaai_leads`; consent text and time stored; honeypot, rate limit and session checks tested; nothing in `kimaai_chats.input` |
| LD-4 | Triggers after N messages and on buying intent, dismissal | Form shows once per session at N; tool shows it on intent; "Not now" stops further prompts; unit and e2e tests |
| LD-5 | Leads admin page, CSV export, notification email | List, filter, delete, transcript link; CSV escapes formulas; `manage_options` enforced; e2e |
| LD-6 | Privacy exporter, eraser, retention, policy text | Tools > Export and Erase Personal Data include leads and linked sessions; retention deletes old leads |
| LD-7 | Sync queue and signed webhook (premium) | Async job per destination, retries with backoff, status in the list; signature verifiable from docs |
| LD-8 | HubSpot destination | Upsert by email; fake HTTP tests; manual smoke test with a test portal |
| LD-9 | Brevo and Mailchimp destinations | Contact upsert; list subscription only with marketing consent; double opt-in default for Mailchimp |
| LD-10 | Pipedrive destination | Person found or created, lead linked; fake HTTP tests |
| LD-11 | Before-handoff trigger | Handoff asks for details first; handoff email and webhook carry the lead email |
| LD-12 | Meeting booking renderable | Click to load; prefill; booking event recorded; Jest and e2e with a stubbed embed |
| LD-13 | Lead score | Score and reasons stored and shown; sent to CRMs; unit tests per rule |

## Sources

1. Chatbase, Collect leads: <https://www.chatbase.co/docs/user-guides/chatbot/actions/collect-leads>
2. Chatbase, webhooks: <https://www.chatbase.co/docs/developer-guides/webhooks>
3. Chatbase, Calendly action: <https://www.chatbase.co/docs/user-guides/chatbot/actions/calendly>
4. Chatbase, Cal.com action: <https://www.chatbase.co/docs/user-guides/chatbot/actions/cal>
5. HubSpot, customer agent lead qualification: <https://knowledge.hubspot.com/customer-agent/set-up-customer-agent-actions-to-qualify-leads>
6. Intercom, enriching leads with Fin Sales Agent: <https://www.intercom.com/help/en/articles/14079086-enriching-leads-with-fin-sales-agent>
7. Calendly, advanced embed: <https://calendly.com/help/advanced-calendly-embed-for-developers> and recipes: <https://developer.calendly.com/api-docs/overview/embedding/recipes>
8. Calendly, notifying the parent window: <https://developer.calendly.com/api-docs/overview/embedding/notifying-the-parent-window>
9. Calendly community, webhooks on the Free plan: <https://community.calendly.com/developer-faq-62/scheduling-api-post-invitees-and-webhooks-now-available-on-the-free-plan-6162>
10. Cal.com, set up your embed: <https://cal.com/docs/core-features/embed/set-up-your-embed>
11. Cal.com, prefill: <https://cal.com/help/embedding/prefill-booking-form-embed>
12. Cal.com, embed events: <https://cal.com/help/embedding/embed-events>
13. HubSpot, contacts API: <https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide>
14. HubSpot, private apps: <https://developers.hubspot.com/docs/guides/apps/private-apps/overview>
15. Brevo, create contact: <https://developers.brevo.com/reference/createcontact> and double opt-in: <https://developers.brevo.com/reference/createdoicontact>
16. Mailchimp, add or update list member: <https://mailchimp.com/developer/marketing/api/list-members/add-or-update-list-member/>
17. Pipedrive, persons: <https://developers.pipedrive.com/docs/api/v1/Persons>
18. Pipedrive, leads: <https://developers.pipedrive.com/docs/api/v1/Leads>
19. Pipedrive, authentication: <https://pipedrive.readme.io/docs/core-api-concepts-authentication>
20. WordPress, personal data exporter: <https://developer.wordpress.org/plugins/privacy/adding-the-personal-data-exporter-to-your-plugin/> and eraser: <https://developer.wordpress.org/plugins/privacy/adding-the-personal-data-eraser-to-your-plugin/>
21. Action Scheduler API: <https://actionscheduler.org/api/>
