The routes live under /wp-json/kimaai/v1/. A call from a logged-in browser sends the WordPress REST nonce, as every WordPress REST call does; a script uses an application password. A route that names a feature is registered only while that feature is not hidden (app/Features/Features.php).
Each route says its access. Internal: the route serves KimaAI’s own admin screens or chat widget and may change or go away in any release without notice, so code outside KimaAI should not call it. Public: the route keeps its path, its arguments and its answer across releases, and changes only after a deprecation.
POST /kimaai/v1/chatbot/lead
- Access: internal
- Permission: anyone; the visitor’s conversation must have started, and one that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: lead-capture
Stores the contact details the visitor left in the lead form of the chat, records that the visitor declined (dismiss), or reports a meeting booked in the calendar (meeting_booked). Five leads per IP address and day; the consent text must be the one the visitor saw; the kimaai_lead_validate filter can refuse a lead.
| Argument | Type | Required | Description |
|---|---|---|---|
action | string | no | submit, dismiss or meeting_booked. Default submit. |
email | string | no | The visitor’s email address. |
name | string | no | The visitor’s name. |
phone | string | no | The visitor’s phone number. |
company | string | no | The visitor’s company. |
consent | boolean | no | True when the visitor agreed to the processing of their details. |
marketing | boolean | no | True when the visitor agreed to marketing. |
consentVersion | string | no | The version of the consent text the form showed. |
trigger | string | no | What opened the form. |
postId | integer | no | The post the chat ran on. Default 0. |
website | string | no | A hidden field that only bots fill in; a filled one is ignored. |
Returns: ok; or an error with 400 (address, consent, refused), 403, 404 (no lead form, no conversation), 429 or 500.
GET /kimaai/v1/leads
- Access: internal
- Permission: a user with the leads capability,
manage_optionsunless thekimaai_leads_capabilityfilter changes it - Tier: free
- Feature: lead-capture
One page of leads for the Leads page, newest first, with their delivery state per destination.
| Argument | Type | Required | Description |
|---|---|---|---|
page | integer | no | The page, from 1. Default 1. |
per_page | integer | no | Leads per page, 1 to 100. Default 25. |
search | string | no | Text to search for in the leads. |
status | string | no | new, dismissed, erased or all. Default new. |
from | string | no | First day, YYYY-MM-DD. |
to | string | no | Last day, YYYY-MM-DD. |
failed | string | no | Only leads whose last delivery to this destination failed; any for any destination. |
Returns: items and total.
DELETE /kimaai/v1/leads/{id}
- Access: internal
- Permission: a user with the leads capability,
manage_optionsunless thekimaai_leads_capabilityfilter changes it - Tier: free
- Feature: lead-capture
Deletes a lead with its delivery state and fires kimaai_lead_erased, unless the lead was erased before.
| Argument | Type | Required | Description |
|---|---|---|---|
id | integer | yes | The lead. |
Returns: ok; 404 for an unknown lead.
GET /kimaai/v1/leads/{id}/conversation
- Access: internal
- Permission: a user with the leads capability,
manage_optionsunless thekimaai_leads_capabilityfilter changes it - Tier: free
- Feature: lead-capture
The conversation the lead came from, so a user who may see leads but not the chat history can read it.
| Argument | Type | Required | Description |
|---|---|---|---|
id | integer | yes | The lead. |
Returns: The conversation’s messages; 404 for an unknown lead.