Conversations and insights 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.

The chat history, the Feedback tab and the Insights page call these routes; all of them need an administrator.

GET /kimaai/v1/chatbot/all

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

Every stored chat message, newest first; with isPlayground, the first message of each conversation held in the settings’ chat preview.

ArgumentTypeRequiredDescription
isPlaygroundbooleannoTrue for the chat preview’s conversations.

Returns: A list of message rows.

POST /kimaai/v1/chatbot/delete

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

Deletes one stored chat message.

ArgumentTypeRequiredDescription
idintegeryesThe message row.

Returns: True when it was deleted.

GET /kimaai/v1/chatbot/sessions

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

One summary row per conversation for the chat history, with its outcome, lead and rating where those features are on.

ArgumentTypeRequiredDescription
isPlaygroundbooleannoTrue for the chat preview’s conversations.

Returns: A list of conversations.

GET /kimaai/v1/chatbot/session/{session_id}

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

All messages of one conversation, with its facts.

ArgumentTypeRequiredDescription
session_idstringyesThe conversation.

Returns: The conversation’s messages.

POST /kimaai/v1/chatbot/session/delete

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

Deletes conversations with everything stored for them, as the retention does.

ArgumentTypeRequiredDescription
session_idsarraynoThe conversations.

Returns: success, session_ids and deleted_count; 400 without conversations.

POST /kimaai/v1/chatbot/feedback/message/delete

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

Deletes answer ratings.

ArgumentTypeRequiredDescription
idsarrayyesThe ratings’ IDs.

Returns: ok, deleted and ids; 400 without valid IDs.

POST /kimaai/v1/chatbot/feedback/csat/delete

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: none

Deletes satisfaction ratings (CSAT).

ArgumentTypeRequiredDescription
idsarrayyesThe ratings’ IDs.

Returns: ok, deleted and ids; 400 without valid IDs.

GET /kimaai/v1/insights/overview

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: free
  • Feature: insights

The overview of the Insights page for the conversations that started in the last range days: conversations, messages per conversation, resolved, unresolved and escalated conversations, and the top pages.

ArgumentTypeRequiredDescription
rangeintegernoDays, 1 to 366. 1 to 366. Default 30.

Returns: range, idleMinutes, kpis and topPages.

GET /kimaai/v1/feedback/analytics/overview

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

The feedback figures of the Feedback tab: ratings, their rate and trend.

ArgumentTypeRequiredDescription
rangeintegernoDays to include. Default 90.
fromstringnoFirst day, YYYY-MM-DD; with to instead of range.
tostringnoLast day, YYYY-MM-DD.

Returns: The figures for the period.

GET /kimaai/v1/feedback/analytics/message-feedback

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

One page of rated answers with their conversation.

ArgumentTypeRequiredDescription
rangeintegernoDays to include. Default 90.
fromstringnoFirst day, YYYY-MM-DD.
tostringnoLast day, YYYY-MM-DD.
pageintegernoThe page, from 1. Default 1.
per_pageintegernoRows per page. Default 25.
ratingintegerno1 for helpful, -1 for not helpful, 0 for both. Default 0.
post_idintegernoOnly answers on this post. Default 0.
providerstringnoOnly answers from this AI provider.
modelstringnoOnly answers from this model.
has_commentintegerno1 for rated answers with a comment only. Default 0.

Returns: The rows and their total.

GET /kimaai/v1/feedback/analytics/csat/summary

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

The satisfaction ratings (CSAT) of a period: average and distribution.

ArgumentTypeRequiredDescription
rangeintegernoDays to include. Default 90.
fromstringnoFirst day, YYYY-MM-DD.
tostringnoLast day, YYYY-MM-DD.

Returns: The summary.

GET /kimaai/v1/feedback/analytics/csat/list

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

One page of satisfaction ratings.

ArgumentTypeRequiredDescription
rangeintegernoDays to include. Default 90.
fromstringnoFirst day, YYYY-MM-DD.
tostringnoLast day, YYYY-MM-DD.
pageintegernoThe page, from 1. Default 1.
per_pageintegernoRows per page. Default 25.
scoreintegernoOnly this number of stars; 0 for all. Default 0.

Returns: The rows and their total.

GET /kimaai/v1/feedback/analytics/items

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

Answer ratings and satisfaction ratings as one list, for the Feedback tab.

ArgumentTypeRequiredDescription
rangeintegernoDays to include. Default 30.
pageintegernoThe page, from 1. Default 1.
per_pageintegernoRows per page. Default 25.
typestringnomessage, csat, or empty for both.
sentimentstringnopositive, neutral, negative, or empty for all.
scoreintegernoOnly this score; 0 for all. Default 0.
has_commentintegerno1 for ratings with a comment only. Default 0.
searchstringnoText to search for.

Returns: The rows and their total.

GET /kimaai/v1/feedback/analytics/incident

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

The conversation around one rated answer, with how it was answered.

ArgumentTypeRequiredDescription
session_idstringyesThe conversation.
message_idstringyesThe rated answer.

Returns: The turns around the answer.

POST /kimaai/v1/feedback/analytics/admin-meta

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: none

Marks a rating as addressed and stores an admin note with it.

ArgumentTypeRequiredDescription
kindstringyesThe kind of rating, message or csat.
ref_idintegeryesThe rating.
addressedbooleannoTrue when it was dealt with.
admin_notestringnoA note for the team.

Returns: The stored state.

GET /kimaai/v1/insights/gaps

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: content-gaps

The topics of the last range days that the knowledge does not answer well, highest gap score first, with why each is flagged, sample questions and the closest page of the vector index.

ArgumentTypeRequiredDescription
rangeintegernoDays, 1 to 366. Default 30.

Returns: The topics with their gap scores.

POST /kimaai/v1/insights/gaps/{id}/pinned-answer

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: content-gaps

Adds a pinned answer, switched off, with the topic’s questions (emails, phone numbers and long digit runs masked); the editor writes the answer.

ArgumentTypeRequiredDescription
idintegeryesThe topic, from 1.

Returns: added and the url of the pinned answers; 404 for an unknown topic.

POST /kimaai/v1/insights/gaps/{id}/eval-case

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: content-gaps

Adds an eval case, switched off, with the topic’s latest question (masked); the editor adds the assertions.

ArgumentTypeRequiredDescription
idintegeryesThe topic, from 1.

Returns: added and the url of the eval cases; 404 for an unknown topic.

POST /kimaai/v1/insights/gaps/{id}/draft

  • Access: internal
  • Permission: an administrator (manage_options) who may also edit posts (edit_posts)
  • Tier: premium
  • Feature: content-gaps

Opens a draft post with the topic as its title.

ArgumentTypeRequiredDescription
idintegeryesThe topic, from 1.

Returns: added and the url of the draft’s editor; 404 for an unknown topic.

GET /kimaai/v1/insights/conversions

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: conversions

The conversions of the last range days: counts, the paid value of orders per currency, the latest orders with the source WooCommerce found, and the latest leads, meetings and forms.

ArgumentTypeRequiredDescription
rangeintegernoDays, 1 to 366. Default 30.

Returns: The counts and the latest conversions.

GET /kimaai/v1/insights/topics

  • Access: internal
  • Permission: an administrator (manage_options)
  • Tier: premium
  • Feature: topics

The topics visitors asked about in the last range days, with their volume, the change against the period before and how those conversations went.

ArgumentTypeRequiredDescription
rangeintegernoDays, 1 to 366. Default 30.

Returns: The topics, the range, whether topics are enabled, and the minimum topic size.

What are your feelings