AISARAISAR
REST API

Аналитика CSAT

Аналитика удовлетворённости клиентов (CSAT) по завершённым диалогам компании. Четыре read-only эндпоинта под `/v1/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": ""
}