ИИ-оценка диалогов
ИИ-оценка диалогов: тон клиента, признак спама и итог каждого обращения (решён ли вопрос, доволен ли клиент). Группа включает выключатель функции для компании, сводку за период и историю обращений диалога; сами оценки приходят в блоке `ai_indicators` ресурсов диалога и принимаются фильтрами `ai_*` списков.
Доступ и тариф
Все эндпоинты требуют активной подписки и тарифа Business и выше (функция ai_indicators); если функция недоступна по тарифу, PUT отвечает 403 с error: feature_not_available. Компания определяется по текущей компании пользователя. Эндпоинты недоступны для embed- и connect-сессий. Лимиты: настройки (GET/PUT /companies/current/ai-indicators) — 60 запросов в минуту на пользователя, сводка и история обращений — 30 в минуту.
Обращение и сроки
Обращение — часть диалога по одному вопросу; оно завершается после 24 часов тишины клиента или при закрытии диалога. Тон и спам оцениваются примерно через 30 минут после последнего сообщения клиента, итог обращения (resolved, satisfied) появляется через 24 часа тишины или при закрытии диалога. Ночной прогон служит страховкой. Пока оценки нет, поле равно null.
Блок `ai_indicators` в ресурсах диалога
Блок добавлен в ресурсы диалога и треда (GET /v1/conversations, GET /v1/conversations/{id}, список тредов). Ключ отсутствует, если функция недоступна по тарифу или выключена в компании; значение null означает, что диалог ещё не оценён.
"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илиnull.is_spam—true/falseилиnull.last_episode— последнее обращение диалога илиnull:ended_at,end_reason(причина завершения: тишина или закрытие диалога),resolved,satisfied(true/false/null),evaluated_at.- Значения, в которых ИИ недостаточно уверен, сервер заменяет на
null(в интерфейсе это «Недостаточно данных»); сырые уверенности наружу не отдаются. Язык диалога в API не публикуется.
Фильтры списков
Параметры принимают GET /v1/conversations, список тредов и счётчики чата (GET /v1/conversations/counters), счётчики учитывают те же условия, что и список:
ai_tone— список через запятую изpositive,neutral,dissatisfied,irritated(не больше четырёх значений).ai_spam—only(только спам) илиexclude(скрыть спам).ai_outcome—unresolved(последнее обращение не решено) илиunsatisfied(клиент недоволен итогом последнего обращения).
ai_* игнорируются без ошибки 422, а список возвращается без фильтрации по ним. Фильтра по языку нет.Сводка за период
- Доступна владельцу и администратору (право
company.update) и руководителю (рольmanager); оператору отвечает403. Параметры периода те же, что у CSAT (period=today/7d/30dлибоfrom+to,timezone), но период не длиннее 92 дней, иначе422. Если функция выключена в компании, отвечает404(error: ai_indicators_inactive). Результат кэшируется на 5 минут. episodes— число завершённых за период обращений;satisfied_pct— целый процент «клиент доволен» среди обращений с уверенным вердиктом (null, если таких нет);satisfied_low_confidence— число обращений периода без уверенного вердикта «доволен/недоволен».irritated_customers— число различных контактов с текущим тономirritated, чьё последнее сообщение пришлось на период;unresolved_episodes— число диалогов, чьё последнее обращение завершилось в периоде и не решено. Счёт учитывает доступ пользователя к каналам, как список чата.links— готовые параметры фильтров списка для перехода от цифры к диалогам;csat—{satisfaction_pct, responded}за период илиnull, если ответов CSAT нет.
Выключение
PUT /v1/companies/current/ai-indicators с enabled=false прекращает оценку и скрывает результаты: блок ai_indicators, фильтры ai_*, сводка и история обращений перестают отдавать данные. Данные не удаляются, при повторном включении прежние оценки снова видны. В ответ на PUT приходит то же состояние, что и у GET. Сообщения, написанные, пока функция была выключена, никогда не оцениваются.
Realtime
Событие conversation.ai_indicators_updated приходит на канал компании (вебхука нет) после дневной оценки через 30 минут паузы клиента, после итога обращения через 24 часа тишины и после оценки при закрытии диалога, только если видимые значения изменились. Ночной прогон служит страховкой; если событие пропущено, свежие значения придут при следующей загрузке списка.
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/companies/current/ai-indicatorsСостояние функции в компании: включена ли и доступна ли по тарифу (право `company.view`) | Состояние функции в компании: включена ли и доступна ли по тарифу (право `company.view`) |
| PUT | /v1/companies/current/ai-indicatorsВключить или выключить ИИ-оценку (`company.update`, полный токен; выключение скрывает результаты, не удаляя их) | Включить или выключить ИИ-оценку (`company.update`, полный токен; выключение скрывает результаты, не удаляя их) |
| GET | /v1/ai-indicators/summaryСводка ИИ-оценки за период (владелец и руководитель) | Сводка ИИ-оценки за период (владелец и руководитель) |
| GET | /v1/conversations/{conversation}/ai-episodesИстория обращений диалога с их оценками (`limit` до 20, новые первыми; только оценённые; `404`, если нет доступа к диалогу или функция выключена) | История обращений диалога с их оценками (`limit` до 20, новые первыми; только оценённые; `404`, если нет доступа к диалогу или функция выключена) |
| POST | /v1/conversations/{conversation}/messages/{message}/ai-ratingОценка оператором ответа ИИ-агента: `verdict` good|bad и необязательный `comment` до 1000 символов; одна оценка на пользователя, повторный вызов её перезаписывает. `422`, если сообщение не ответ ИИ; `404`, если диалог или сообщение недоступны; 60 запросов в минуту | Оценка оператором ответа ИИ-агента: `verdict` good|bad и необязательный `comment` до 1000 символов; одна оценка на пользователя, повторный вызов её перезаписывает. `422`, если сообщение не ответ ИИ; `404`, если диалог или сообщение недоступны; 60 запросов в минуту |
| DELETE | /v1/conversations/{conversation}/messages/{message}/ai-ratingСнять свою оценку ответа ИИ (в ответе `verdict: null`) | Снять свою оценку ответа ИИ (в ответе `verdict: null`) |
Примеры
Состояние функции в компании
Запрос
curl "https://api.aisar.app/v1/companies/current/ai-indicators" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"enabled": true,
"available": true,
"updated_at": "2026-11-13T08:00:00.000000Z",
"updated_by_name": "Aida Nurlanova"
}
}Выключить ИИ-оценку
Запрос
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}'Ответ
{
"data": {
"enabled": false,
"available": true,
"updated_at": "2026-11-13T09:30:00.000000Z",
"updated_by_name": "Aida Nurlanova"
}
}Сводка за 30 дней
Запрос
curl "https://api.aisar.app/v1/ai-indicators/summary?period=30d&timezone=Asia/Almaty" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"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
}
}История обращений диалога
Запрос
curl "https://api.aisar.app/v1/conversations/750/ai-episodes?limit=5" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"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"
}
]
}Оценить ответ ИИ-агента
Запрос
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": "Назвал неверную цену доставки"}'Ответ
{
"data": {
"message_id": 91234,
"verdict": "bad",
"comment": "Назвал неверную цену доставки"
}
}Снять свою оценку ответа ИИ-агента
Запрос
curl -X DELETE "https://api.aisar.app/v1/conversations/750/messages/91234/ai-rating" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"message_id": 91234,
"verdict": null
}
}