Clomni

Scope и endpoint: отчёты, CSAT, SLA

Обновлено: 11 ноября 2026 · 6 мин чтения

Scope для цифр отчётов, удовлетворённости клиентов и SLA. Чтобы выгружать цифры в Power BI, Looker Studio, Metabase и подобные инструменты, обычно хватает reports:read. В endpoint отчётов время передаётся в секундах Unix.

Шаги

  1. 1

    Как читать эту статью

    • Пути пишутся после https://api.clomni.ai/v1: GET /v1/agents означает https://api.clomni.ai/v1/agents. В пути нет ID workspace, потому что токен привязан к одному workspace.
    • В каждом запросе есть заголовок Authorization: Bearer clomni_pat_xxx. Как получить токен: Токены и аутентификация в Developer API.
    • Риск: низкий (нет персональных данных), средний (читает данные клиентов или меняет внутренние данные), высокий (отправляет клиентам, удаляет, массово выгружает, меняет рабочие настройки).
    • Каждый scope проходит review, в public app тоже. Подробнее: Review: проверка scope и причины отказа.
    • «Дополнительно даёт»: write и manage дают и read того же ресурса. send, delete, publish, assign, run ничего не дают.
    • Если endpoint открывается несколькими scope, достаточно одного. Без scope API отвечает 403 insufficient_scope, в ответе есть required_scopes.
    • Каждый POST принимает заголовок Idempotency-Key: повторный запрос не выполняется дважды.
  2. 2

    Читать отчёты (reports:read)

    Читает сводные цифры: количество диалогов и сообщений, время первого ответа и решения, итоги по операторам, inbox, меткам, командам и каналам, данные в реальном времени, показатели AI-агента и ботов, события отчётов. Персональных данных клиентов нет, поэтому риск низкий. Это основной scope для BI-инструмента.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/conversations/{conversation_id}/reporting_events: События отчётов диалога
    • GET /v1/live_reports/conversation_metrics: Количество диалогов в реальном времени
    • GET /v1/live_reports/grouped_conversation_metrics: Диалоги в реальном времени по операторам или командам
    • GET /v1/reporting_events: События отчётов
    • GET /v1/reports: Временной ряд отчёта
    • GET /v1/reports/agents: Итоги по операторам
    • GET /v1/reports/bot_metrics: Показатели AI-агента и ботов
    • GET /v1/reports/bot_summary: Итоги AI-агента и ботов
    • GET /v1/reports/conversation_traffic: Нагрузка диалогов по часам и дням недели
    • GET /v1/reports/conversations: Открытые диалоги по операторам
    • GET /v1/reports/conversations_summary: Сводка по диалогам
    • GET /v1/reports/first_response_time_distribution: Распределение времени первого ответа
    • GET /v1/reports/inbox_label_matrix: Диалоги по inbox и меткам
    • GET /v1/reports/inboxes: Итоги по inbox
    • GET /v1/reports/labels: Итоги по меткам
    • GET /v1/reports/outgoing_messages_count: Количество исходящих сообщений
    • GET /v1/reports/summary: Итоги отчёта
    • GET /v1/reports/teams: Итоги по командам
    • GET /v1/summary_reports/agent: Сводный отчёт по операторам
    • GET /v1/summary_reports/channel: Сводный отчёт по каналам
    • GET /v1/summary_reports/inbox: Сводный отчёт по inbox
    • GET /v1/summary_reports/label: Сводный отчёт по меткам
    • GET /v1/summary_reports/team: Сводный отчёт по командам

    Пример:

    curl "https://api.clomni.ai/v1/reports?metric=conversations_count&type=account&since=1793491200&until=1794096000&group_by=day&timezone_offset=4" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/live_reports/conversation_metrics" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Читать ответы CSAT (csat:read)

    Читает оценки удовлетворённости (CSAT), комментарии и итоговое распределение. В комментариях собственный текст клиента, поэтому риск средний.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/csat_survey_responses: Ответы CSAT
    • GET /v1/csat_survey_responses/metrics: Итоги CSAT

    Пример:

    curl "https://api.clomni.ai/v1/csat_survey_responses?since=1793491200&until=1794096000&page=1" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/csat_survey_responses/metrics" \
  -H "Authorization: Bearer clomni_pat_xxx"
  4. 4

    Видеть SLA (sla:read)

    Читает правила SLA и результаты SLA по диалогам, включая нарушения.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/applied_slas: Результаты SLA по диалогам
    • GET /v1/applied_slas/metrics: Итоги SLA
    • GET /v1/sla_policies: Список правил SLA
    • GET /v1/sla_policies/{sla_policy_id}: Получить правило SLA

    Пример:

    curl "https://api.clomni.ai/v1/sla_policies" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/applied_slas" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Менять правила SLA (sla:write)

    Создаёт, меняет и удаляет правила SLA: время первого ответа, следующего ответа и решения, считать ли только рабочие часы.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: sla:read.

    Endpoint:

    • POST /v1/sla_policies: Создать правило SLA
    • PATCH /v1/sla_policies/{sla_policy_id}: Изменить правило SLA
    • DELETE /v1/sla_policies/{sla_policy_id}: Удалить правило SLA

    Пример:

    curl -X POST "https://api.clomni.ai/v1/sla_policies" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standart", "first_response_time_threshold": 900, "resolution_time_threshold": 28800, "only_during_business_hours": true}'
  6. 6

    Связанные статьи

Документ

Платформа для разработчиков: руководство v1.0 · 41 стр. Открыть Скачать