---
kind: rest
area: chatbot
tier: free
summary: The routes of the chat history, the feedback and the Insights pages in the admin.
---

# 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.

| Argument       | Type    | Required | Description                                |
| -------------- | ------- | -------- | ------------------------------------------ |
| `isPlayground` | boolean | no       | True 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.

| Argument | Type    | Required | Description      |
| -------- | ------- | -------- | ---------------- |
| `id`     | integer | yes      | The 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.

| Argument       | Type    | Required | Description                                |
| -------------- | ------- | -------- | ------------------------------------------ |
| `isPlayground` | boolean | no       | True 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.

| Argument     | Type   | Required | Description       |
| ------------ | ------ | -------- | ----------------- |
| `session_id` | string | yes      | The 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.

| Argument      | Type  | Required | Description        |
| ------------- | ----- | -------- | ------------------ |
| `session_ids` | array | no       | The 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.

| Argument | Type  | Required | Description       |
| -------- | ----- | -------- | ----------------- |
| `ids`    | array | yes      | The 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).

| Argument | Type  | Required | Description       |
| -------- | ----- | -------- | ----------------- |
| `ids`    | array | yes      | The 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.

| Argument | Type    | Required | Description                             |
| -------- | ------- | -------- | --------------------------------------- |
| `range`  | integer | no       | Days, 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.

| Argument | Type    | Required | Description                                            |
| -------- | ------- | -------- | ------------------------------------------------------ |
| `range`  | integer | no       | Days to include. Default `90`.                         |
| `from`   | string  | no       | First day, `YYYY-MM-DD`; with `to` instead of `range`. |
| `to`     | string  | no       | Last 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.

| Argument      | Type    | Required | Description                                                 |
| ------------- | ------- | -------- | ----------------------------------------------------------- |
| `range`       | integer | no       | Days to include. Default `90`.                              |
| `from`        | string  | no       | First day, `YYYY-MM-DD`.                                    |
| `to`          | string  | no       | Last day, `YYYY-MM-DD`.                                     |
| `page`        | integer | no       | The page, from 1. Default `1`.                              |
| `per_page`    | integer | no       | Rows per page. Default `25`.                                |
| `rating`      | integer | no       | 1 for helpful, -1 for not helpful, 0 for both. Default `0`. |
| `post_id`     | integer | no       | Only answers on this post. Default `0`.                     |
| `provider`    | string  | no       | Only answers from this AI provider.                         |
| `model`       | string  | no       | Only answers from this model.                               |
| `has_comment` | integer | no       | 1 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.

| Argument | Type    | Required | Description                    |
| -------- | ------- | -------- | ------------------------------ |
| `range`  | integer | no       | Days to include. Default `90`. |
| `from`   | string  | no       | First day, `YYYY-MM-DD`.       |
| `to`     | string  | no       | Last 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.

| Argument   | Type    | Required | Description                                        |
| ---------- | ------- | -------- | -------------------------------------------------- |
| `range`    | integer | no       | Days to include. Default `90`.                     |
| `from`     | string  | no       | First day, `YYYY-MM-DD`.                           |
| `to`       | string  | no       | Last day, `YYYY-MM-DD`.                            |
| `page`     | integer | no       | The page, from 1. Default `1`.                     |
| `per_page` | integer | no       | Rows per page. Default `25`.                       |
| `score`    | integer | no       | Only 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.

| Argument      | Type    | Required | Description                                          |
| ------------- | ------- | -------- | ---------------------------------------------------- |
| `range`       | integer | no       | Days to include. Default `30`.                       |
| `page`        | integer | no       | The page, from 1. Default `1`.                       |
| `per_page`    | integer | no       | Rows per page. Default `25`.                         |
| `type`        | string  | no       | `message`, `csat`, or empty for both.                |
| `sentiment`   | string  | no       | `positive`, `neutral`, `negative`, or empty for all. |
| `score`       | integer | no       | Only this score; 0 for all. Default `0`.             |
| `has_comment` | integer | no       | 1 for ratings with a comment only. Default `0`.      |
| `search`      | string  | no       | Text 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.

| Argument     | Type   | Required | Description       |
| ------------ | ------ | -------- | ----------------- |
| `session_id` | string | yes      | The conversation. |
| `message_id` | string | yes      | The 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.

| Argument     | Type    | Required | Description                              |
| ------------ | ------- | -------- | ---------------------------------------- |
| `kind`       | string  | yes      | The kind of rating, `message` or `csat`. |
| `ref_id`     | integer | yes      | The rating.                              |
| `addressed`  | boolean | no       | True when it was dealt with.             |
| `admin_note` | string  | no       | A 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.

| Argument | Type    | Required | Description                 |
| -------- | ------- | -------- | --------------------------- |
| `range`  | integer | no       | Days, 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.

| Argument | Type    | Required | Description        |
| -------- | ------- | -------- | ------------------ |
| `id`     | integer | yes      | The 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.

| Argument | Type    | Required | Description        |
| -------- | ------- | -------- | ------------------ |
| `id`     | integer | yes      | The 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.

| Argument | Type    | Required | Description        |
| -------- | ------- | -------- | ------------------ |
| `id`     | integer | yes      | The 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.

| Argument | Type    | Required | Description                 |
| -------- | ------- | -------- | --------------------------- |
| `range`  | integer | no       | Days, 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.

| Argument | Type    | Required | Description                 |
| -------- | ------- | -------- | --------------------------- |
| `range`  | integer | no       | Days, 1 to 366. Default 30. |

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