Leads REST routes

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.

ArgumentTypeRequiredDescription
actionstringnosubmit, dismiss or meeting_booked. Default submit.
emailstringnoThe visitor’s email address.
namestringnoThe visitor’s name.
phonestringnoThe visitor’s phone number.
companystringnoThe visitor’s company.
consentbooleannoTrue when the visitor agreed to the processing of their details.
marketingbooleannoTrue when the visitor agreed to marketing.
consentVersionstringnoThe version of the consent text the form showed.
triggerstringnoWhat opened the form.
postIdintegernoThe post the chat ran on. Default 0.
websitestringnoA 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_options unless the kimaai_leads_capability filter changes it
  • Tier: free
  • Feature: lead-capture

One page of leads for the Leads page, newest first, with their delivery state per destination.

ArgumentTypeRequiredDescription
pageintegernoThe page, from 1. Default 1.
per_pageintegernoLeads per page, 1 to 100. Default 25.
searchstringnoText to search for in the leads.
statusstringnonew, dismissed, erased or all. Default new.
fromstringnoFirst day, YYYY-MM-DD.
tostringnoLast day, YYYY-MM-DD.
failedstringnoOnly 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_options unless the kimaai_leads_capability filter 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.

ArgumentTypeRequiredDescription
idintegeryesThe lead.

Returns: ok; 404 for an unknown lead.

GET /kimaai/v1/leads/{id}/conversation

  • Access: internal
  • Permission: a user with the leads capability, manage_options unless the kimaai_leads_capability filter 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.

ArgumentTypeRequiredDescription
idintegeryesThe lead.

Returns: The conversation’s messages; 404 for an unknown lead.

What are your feelings