Skip to content
AISARAISAR
REST API

AI conversation review

AI conversation review: customer tone, a spam flag and the outcome of each inquiry (was the issue solved, is the customer satisfied). The group covers the company-level switch, the period summary and a conversation's inquiry history; the assessments themselves arrive in the `ai_indicators` block of conversation resources and are filtered with the `ai_*` list parameters.

Access and plan

All endpoints require an active subscription and the Business plan or above (the ai_indicators feature); Kids companies get 403. The company is the user's current company. The endpoints are not available to embed and connect sessions.

Inquiries and timing

An inquiry is a part of a conversation about one question; it ends after 24 hours of customer silence or when the conversation is closed. Tone and spam are assessed about 30 minutes after the customer's last message, and the inquiry outcome (resolved, satisfied) appears after 24 hours of silence or when the conversation is closed. The nightly run is a safety net. While there is no assessment the field is null.

The `ai_indicators` block in conversation resources

The block is added to conversation and thread resources (GET /v1/conversations, GET /v1/conversations/{id}, the thread list). The key is absent when the feature is unavailable on the plan or switched off for the company; the value null means the conversation has not been assessed yet.

json
"ai_indicators": {
  "tone": "irritated",
  "is_spam": false,
  "analyzed_at": "2026-11-14T01:42:10.000000Z",
  "last_episode": {
    "ended_at": "2026-11-13T09:15:00.000000Z",
    "end_reason": "silence",
    "resolved": false,
    "satisfied": null,
    "evaluated_at": "2026-11-14T01:42:10.000000Z"
  }
}
  • tone — positive, neutral, dissatisfied, irritated or null.
  • is_spam — true/false or null.
  • last_episode — the conversation's latest inquiry or null: ended_at, end_reason (why it ended: silence or the conversation being closed), resolved, satisfied (true/false/null), evaluated_at.
  • Values the AI is not confident enough about are replaced by the server with null (shown in the UI as "Not enough data"); raw confidence scores are never returned. The conversation language is not exposed in the API.

List filters

The parameters are accepted by GET /v1/conversations, the thread list and the chat counters (GET /v1/conversations/counters); counters honour the same conditions as the list:

  • ai_tone — a comma-separated list of positive,neutral,dissatisfied,irritated (at most four values).
  • ai_spam — only (spam only) or exclude (hide spam).
  • ai_outcome — unresolved (the latest inquiry was not solved) or unsatisfied (the customer was unhappy with the latest inquiry).
When the feature is unavailable on the plan or switched off, the ai_* parameters are ignored without a 422 and the list is returned unfiltered by them. There is no language filter.

Period summary

  • Available to the owner and admin (the company.update permission) and the manager (the manager role); operators get 403. The period parameters are the same as in CSAT (period = today/7d/30d or from+to, timezone), but the period may not exceed 92 days, otherwise 422. When the feature is switched off for the company the endpoint answers 404 (error: ai_indicators_inactive). The result is cached for 5 minutes.
  • episodes — the number of inquiries that ended in the period; satisfied_pct — the whole-number percentage of "customer satisfied" among inquiries with a confident verdict (null when there are none); satisfied_low_confidence — the number of inquiries in the period without a confident satisfied/unsatisfied verdict.
  • irritated_customers — the number of distinct contacts whose current tone is irritated and whose last message fell in the period; unresolved_episodes — the number of conversations whose latest inquiry ended in the period unsolved. Counts honour the user's channel access, like the chat list.
  • links — ready-made list filter parameters to go from a number to the conversations; csat — {satisfaction_pct, responded} for the period or null when there are no CSAT answers.

Switching off

PUT /v1/companies/current/ai-indicators with enabled=false stops assessment and hides results: the ai_indicators block, the ai_* filters, the summary and the inquiry history stop returning data. Data is not deleted; the PUT response has the same shape as GET; switching back on makes the earlier assessments visible again. Messages written while the feature was off are never assessed.

Realtime

The company channel receives conversation.ai_indicators_updated (there is no webhook) after the daytime assessment 30 minutes into a customer's pause, after the inquiry outcome following 24 hours of silence, and after the assessment on closing a conversation, only when the visible values changed. The nightly run is a safety net; if an event is missed, fresh values arrive on the next list load.

Endpoints

MethodPath
GET/v1/companies/current/ai-indicators

Feature state for the company: whether it is on and available on the plan (`company.view`)

PUT/v1/companies/current/ai-indicators

Switch AI review on or off (`company.update`, full token; switching off hides results without deleting them)

GET/v1/ai-indicators/summary

AI review summary for a period (owner and manager)

GET/v1/conversations/{conversation}/ai-episodes

A conversation's inquiry history with their assessments (`limit` up to 20, newest first, assessed only; `404` when the conversation is not accessible or the feature is off)

POST/v1/conversations/{conversation}/messages/{message}/ai-rating

Operator rating of an AI agent answer: `verdict` good|bad and an optional `comment` up to 1000 chars; one rating per user, a repeat call overwrites it. `422` if the message is not an AI answer; `404` if the conversation or message is not accessible; 60 requests per minute

DELETE/v1/conversations/{conversation}/messages/{message}/ai-rating

Remove your own rating of an AI answer (the response has `verdict: null`)

Examples

Feature state for the company

Request

bash
curl "https://api.aisar.app/v1/companies/current/ai-indicators" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

json
{
  "data": {
    "enabled": true,
    "available": true,
    "updated_at": "2026-11-13T08:00:00.000000Z",
    "updated_by_name": "Aida Nurlanova"
  }
}

Switch AI review off

Request

bash
curl -X PUT "https://api.aisar.app/v1/companies/current/ai-indicators" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Response

json
{
  "data": {
    "enabled": false,
    "available": true,
    "updated_at": "2026-11-13T09:30:00.000000Z",
    "updated_by_name": "Aida Nurlanova"
  }
}

Summary for 30 days

Request

bash
curl "https://api.aisar.app/v1/ai-indicators/summary?period=30d&timezone=Asia/Almaty" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

json
{
  "data": {
    "episodes": 214,
    "satisfied_pct": 82,
    "satisfied_low_confidence": 12,
    "irritated_customers": 7,
    "unresolved_episodes": 19,
    "links": {
      "irritated": { "ai_tone": "irritated" },
      "unresolved": { "ai_outcome": "unresolved" }
    },
    "csat": null
  }
}

A conversation's inquiry history

Request

bash
curl "https://api.aisar.app/v1/conversations/750/ai-episodes?limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

json
{
  "data": [
    {
      "started_at": "2026-11-12T10:03:00.000000Z",
      "ended_at": "2026-11-13T09:15:00.000000Z",
      "end_reason": "silence",
      "resolved": false,
      "satisfied": null,
      "tone": "irritated",
      "evaluated_at": "2026-11-14T01:42:10.000000Z"
    }
  ]
}

Rate an AI agent answer

Request

bash
curl -X POST "https://api.aisar.app/v1/conversations/750/messages/91234/ai-rating" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"verdict": "bad", "comment": "Назвал неверную цену доставки"}'

Response

json
{
  "data": {
    "message_id": 91234,
    "verdict": "bad",
    "comment": "Назвал неверную цену доставки"
  }
}

Remove your rating of an AI agent answer

Request

bash
curl -X DELETE "https://api.aisar.app/v1/conversations/750/messages/91234/ai-rating" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

json
{
  "data": {
    "message_id": 91234,
    "verdict": null
  }
}