---
name: kimaai_lead_saved
type: action
since: 1.6.0
tier: free
feature: lead-capture
area: leads-customer-centre
summary: Fires when a visitor left their contact details in the chat and the lead was stored.
parameters:
  - name: lead_id
    type: int
    description: The lead's ID. A visitor who sends the form again in the same conversation replaces the details; the ID stays the same.
  - name: lead
    type: array
    description: The stored details, which are personal data. session_id, user_id (0 for a visitor), status (new), email, name, phone and company (null when the form does not ask for them or they were left empty), trigger_type, post_id, consent_text, consent_at and marketing_opt_in.
surfaces: [chatbot]
---

# kimaai_lead_saved

## When it fires

When a visitor sent the chatbot's lead form and KimaAI stored the lead, in the visitor's request to `POST /kimaai/v1/chatbot/lead`. The form is checked first: lead capture is on, the visitor holds the conversation, at most five leads per IP address and day, a valid email address, consent given to the text the form showed, and `kimaai_lead_validate`. A refused form, "Not now" and a form only a bot fills in (its hidden honeypot field) do not fire it.

`trigger_type` says what showed the form: `messages`, `intent`, `handoff`, `action`, or empty. `post_id` is the page the chat ran on, 0 when the widget did not know it.

KimaAI hooks it itself: the email to the notification address of the lead settings (priority 10) and, with Pro, the lead score (5), the conversion in Insights (10) and the lead sync to the CRMs and the lead webhook (20), which sends in the background. The score is stored on the lead, not added to `$lead`. Your callback runs before the visitor gets an answer, so do nothing slow in it: schedule it, as the lead sync does.

## Example

```php
add_action(
  'kimaai_lead_saved',
  function (int $lead_id, array $lead): void {
    // Which pages and triggers bring leads, for your own report: counts only, no personal data.
    $counts = get_option('my_theme_lead_counts', []);
    $key = $lead['post_id'] . ':' . $lead['trigger_type'];
    $counts[$key] = ($counts[$key] ?? 0) + 1;

    update_option('my_theme_lead_counts', $counts, false);
  },
  10,
  2
);
```

`$lead` holds the visitor's email address and whatever else the form asked for. Keep it out of logs, and pass it on only where the consent text the visitor agreed to (`consent_text`) allows it. To send leads to a CRM that KimaAI does not connect, the Lead webhook of the Pro connections sends each lead as a signed request and tries again when the receiver fails.

## Related

- `kimaai_lead_validate`: refuses a lead before it is stored.
- `kimaai_lead_event`: fires when the visitor of a lead booked a meeting.
- `kimaai_lead_erased`: fires when the lead's details were erased or the lead was deleted.
- `kimaai:chatbot`: the browser event with the type `lead` when the form was sent.
