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

Аналитика CSAT

Аналитика удовлетворённости клиентов (CSAT) по завершённым диалогам компании. Четыре read-only эндпоинта под /v1/csat агрегируют результаты опросов удовлетворённости за выбранный период: сводные метрики, разбивки, динамику по дням и список диалогов с негативной оценкой.

Доступ и включение CSAT

Все четыре эндпоинта требуют активной подписки и права company.view; кроме того, CSAT должен быть включён в настройках компании — если опросы выключены, любой из эндпоинтов отвечает 404.

Параметры периода

Общие параметры периода одинаковы для всех четырёх эндпоинтов:

  • period — today, 7d, 30d (по умолчанию 7d), либо явный диапазон from+to (даты YYYY-MM-DD; применяется только когда заданы оба значения, to должен быть ≥ from).
  • timezone — IANA-зона для расчёта границ суток (по умолчанию UTC).

Что возвращает каждый эндпоинт

  • GET /csat/metrics — сводка: sent (отправлено — опросы в статусах pending/responded/expired), responded, positive, negative, satisfaction_pct (доля позитивных среди ответивших), response_rate_pct (доля ответивших среди отправленных) и delta — изменение satisfaction_pct относительно предыдущего периода той же длины.
  • GET /csat/breakdowns — две разбивки ответивших опросов: by_participant (по сотруднику или AI-агенту) и by_channel (по типу канала).
  • GET /csat/trend — массив по дням периода (дни без ответов заполнены нулями).
  • GET /csat/conversations — пагинированный список диалогов только с негативной оценкой; дополнительно фильтруется по channel_type_key и по паре member_type (user|ai_agent)+member_id (оба параметра обязательны вместе), поддерживает per_page (1–100, по умолчанию 20) и page (по умолчанию 1).

Формат ответа

Ответ conversations обёрнут в { data: { items, pagination } }, остальные три — в { data: ... }.

Эндпоинты

МетодПуть
GET/v1/csat/metrics

Сводные метрики CSAT за период (+delta к прошлому периоду)

GET/v1/csat/breakdowns

Разбивка удовлетворённости по участникам и каналам

GET/v1/csat/trend

Динамика удовлетворённости по дням

GET/v1/csat/conversations

Список диалогов с негативной оценкой (пагинация)

Примеры

Сводные метрики за 30 дней

Запрос

bash
curl "https://api.aisar.app/v1/csat/metrics?period=30d" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "sent": 210,
    "responded": 168,
    "positive": 149,
    "negative": 19,
    "satisfaction_pct": 89,
    "response_rate_pct": 80,
    "delta": 4
  }
}

Разбивка по участникам и каналам

Запрос

bash
curl "https://api.aisar.app/v1/csat/breakdowns?period=30d" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "by_participant": [
      {
        "member_type": "user",
        "member_id": 12,
        "name": "Aida Nurlanova",
        "is_ai": false,
        "responded": 92,
        "positive": 84,
        "negative": 8,
        "satisfaction_pct": 91
      },
      {
        "member_type": "ai_agent",
        "member_id": 4,
        "name": "Support Assistant",
        "is_ai": true,
        "responded": 76,
        "positive": 65,
        "negative": 11,
        "satisfaction_pct": 86
      }
    ],
    "by_channel": [
      { "channel_type_key": "whatsapp", "responded": 118, "positive": 106 },
      { "channel_type_key": "instagram", "responded": 50, "positive": 43 }
    ]
  }
}

Динамика по дням (гэпы заполнены нулями)

Запрос

bash
curl "https://api.aisar.app/v1/csat/trend?period=7d&timezone=Asia/Almaty" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": [
    { "date": "2026-03-09", "responded": 0, "positive": 0, "negative": 0, "satisfaction_pct": 0 },
    { "date": "2026-03-10", "responded": 22, "positive": 20, "negative": 2, "satisfaction_pct": 91 },
    { "date": "2026-03-11", "responded": 18, "positive": 15, "negative": 3, "satisfaction_pct": 83 }
  ]
}

Диалоги с негативной оценкой (фильтр по каналу)

Запрос

bash
curl "https://api.aisar.app/v1/csat/conversations?period=30d&channel_type_key=whatsapp&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "items": [
      {
        "id": 5012,
        "conversation_id": 8841,
        "responded_at": "2026-03-15T09:42:11+00:00",
        "channel_type_key": "whatsapp",
        "raw_response": "Долго ждал ответа",
        "contact": {
          "id": 3307,
          "name": "Ivan Petrov"
        },
        "participants": [
          { "name": "Aida Nurlanova", "is_ai": false }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 20,
      "total": 1,
      "lastPage": 1
    }
  }
}

CSAT выключен в компании (404)

Запрос

bash
curl "https://api.aisar.app/v1/csat/metrics" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "message": ""
}