Перейти к содержимому
AISARAISAR
REST API

ИИ-оценка диалогов

ИИ-оценка диалогов: тон клиента, признак спама и итог каждого обращения (решён ли вопрос, доволен ли клиент). Группа включает выключатель функции для компании, сводку за период и историю обращений диалога; сами оценки приходят в блоке `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 означает, что диалог ещё не оценён.

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 или 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`)

PUT/v1/companies/current/ai-indicators

Включить или выключить ИИ-оценку (`company.update`, полный токен; выключение скрывает результаты, не удаляя их)

GET/v1/ai-indicators/summary

Сводка ИИ-оценки за период (владелец и руководитель)

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

История обращений диалога с их оценками (`limit` до 20, новые первыми; только оценённые; `404`, если нет доступа к диалогу или функция выключена)

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

Оценка оператором ответа ИИ-агента: `verdict` good|bad и необязательный `comment` до 1000 символов; одна оценка на пользователя, повторный вызов её перезаписывает. `422`, если сообщение не ответ ИИ; `404`, если диалог или сообщение недоступны; 60 запросов в минуту

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

Снять свою оценку ответа ИИ (в ответе `verdict: null`)

Примеры

Состояние функции в компании

Запрос

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

Ответ

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

Выключить ИИ-оценку

Запрос

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}'

Ответ

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

Сводка за 30 дней

Запрос

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

Ответ

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
  }
}

История обращений диалога

Запрос

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

Ответ

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"
    }
  ]
}

Оценить ответ ИИ-агента

Запрос

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": "Назвал неверную цену доставки"}'

Ответ

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

Снять свою оценку ответа ИИ-агента

Запрос

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

Ответ

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