Лиды, журнал и статистика

Просмотр и выгрузка лидов, чтение необработанного журнала активности в чате и получение агрегированной статистики.

Все эндпоинты на этой странице требуют активной оплаченной подписки. Если подписка истекла и льготный период завершился, они возвращают ошибку unpaid. Кроме неё любой из них может вернуть системные ошибки key, ban и db; они описаны в разделе Авторизация и соглашения. Эндпоинт-специфичные ошибки указаны в таблицах ниже.

Статусы лидов

Все поля фильтрации и ответов, связанные со статусом лида, используют числовые коды.

Полные правила переходов и условия отправки постбэков — в разделе Жизненный цикл лида.

Список лидов

GET /api/leads/list.json

Возвращает лиды текущего аккаунта, соответствующие фильтрам, от новых к старым.

{
  "status": "ok",
  "data": [
    {
      "id": 1001,
      "campaign": 12,
      "bot": 7,
      "click": "abc456xyz",
      "subscriber": 9876543210,
      "username": "alice",
      "status": 2,
      "start_time": 1747735200,
      "join_time": 1747735260,
      "leave_time": 0,
      "created": 1747735200
    }
  ]
}

data — массив лидов (пустой [], если ничего не найдено); поля total в ответе нет. username — пустая строка, если у подписчика нет username в Telegram. click — пустая строка, если подписчик пришёл без click-payload (например, открыл ссылку бота напрямую, а не через диплинк). start_time, join_time, leave_time и created — Unix-время в секундах; значение 0 означает, что событие ещё не произошло (например, join_time равен 0, пока лид находится в статусе wait или hold).

Счётчики по статусам

GET /api/leads/summary.json

Возвращает количество лидов в разбивке по каждому статусу для текущего фильтра. Сам фильтр status здесь намеренно игнорируется — возвращается полная разбивка по всем статусам, поэтому интерфейс может показать общую картину и позволить переключаться между статусами.

{
  "status": "ok",
  "total": 540,
  "counts": {
    "0": 50,
    "1": 12,
    "2": 420,
    "3": 35,
    "4": 23
  }
}

Поля total и counts лежат на верхнем уровне ответа (не во вложенном объекте data). counts — карта, где ключ — код статуса лида в виде строки, а значение — количество лидов в этом статусе. total — сумма по всем статусам.

Выгрузка лидов в CSV

GET /api/leads/export.csv

Отдаёт отфильтрованные лиды текущего аккаунта в виде файла CSV для скачивания. Принимает те же фильтры, что и список лидов, но без пагинации: выгружается весь подходящий набор (не более 100000 строк).

В отличие от остальных эндпоинтов, ответ — не JSON. Это text/csv; charset=utf-8 c UTF-8 BOM (чтобы кириллица в названиях кампаний корректно открывалась в Excel) и заголовком Content-Disposition: attachment; filename="leads-ГГГГММДД.csv".

Строка заголовка и порядок столбцов:

created,status,subscriber,username,campaign,bot,click,started,joined,left

• status — словесное название (wait, hold, approve, cancel, trash; для неизвестного кода — само число).
• created, started, joined, left — время в UTC в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС; пустая строка, если событие ещё не произошло.
• campaign — название кампании (если оно пустое — её код, иначе #<id>).
• bot — username бота (если он пустой — #<id>).

Если запрос не прошёл ещё до начала отдачи файла, возвращается обычный JSON-ответ с ошибкой (например, db). После того как заголовок CSV отправлен, ответ уже зафиксирован, поэтому сбой при чтении строки просто завершает поток — клиент получает укороченный файл.

Журнал активности в чате

GET /api/journal/list.json

Возвращает журнал активности одного чата — все события вступления и выхода, включая органическую активность (пользователи, вступившие без запуска бота), от новых к старым. Это необработанный источник динамики канала; органические события не создают лидов и не отправляют постбэки. Эндпоинт привязан к конкретной паре бот + чат, поэтому оба параметра обязательны.

{
  "status": "ok",
  "data": [
    {
      "id": 5001,
      "chat": -1001234567890,
      "subscriber": 9876543210,
      "username": "alice",
      "action": 0,
      "lead": 1001,
      "time": 1747735260
    }
  ]
}

data — массив записей (пустой [], если ничего не найдено); поля total в ответе нет. action — числовой код действия (см. таблицу ниже), а не строка. lead — ID связанного лида или 0 для органической активности. time — Unix-время в секундах.

Выгрузка журнала в CSV

GET /api/journal/list.csv

Отдаёт журнал активности одного чата в виде файла CSV для скачивания. Принимает те же параметры области и фильтры, что и журнал активности (bot и chat обязательны, опционально action/paid/from/to), но без пагинации: выгружается весь подходящий набор (не более 100000 строк).

В отличие от JSON-эндпоинтов, ответ — text/csv; charset=utf-8 c UTF-8 BOM и заголовком Content-Disposition: attachment; filename="activity-ГГГГММДД.csv".

Строка заголовка и порядок столбцов:

time,subscriber,username,action,type

• time — время события в UTC в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС.
• action — словесное название действия (join, leave, ban, request).
• type — paid, если запись привязана к лиду, иначе organic.

Поведение при ошибках — как у выгрузки лидов: сбой до начала отдачи возвращает JSON-ошибку (func/access/db), а после отправки заголовка CSV поток просто завершается.

Сводная статистика

GET /api/stats/summary.json

Агрегированные счётчики за период (по умолчанию — последние 30 дней) по всему аккаунту или по одной кампании. Считается в реальном времени из актуальных данных: лиды учитываются по своему текущему статусу (срез на момент запроса), поэтому пять статусов в сумме дают общее число запусков. Ответ кешируется на несколько минут, так что цифры обновляются с небольшой задержкой.

{
  "status": "ok",
  "totals": {
    "wait": 50,
    "hold": 12,
    "approve": 420,
    "cancel": 35,
    "trash": 23,
    "org_join": 150,
    "org_leave": 42
  },
  "starts": 540,
  "confirms": 420,
  "unsubs": 35,
  "lefts": 23,
  "cr": 0.7777777777777778
}

Все поля лежат на верхнем уровне ответа (не во вложенном объекте data). totals — это семь базовых счётчиков: пять статусов лидов (wait, hold, approve, cancel, trash) плюс органические org_join и org_leave. Производные поля:

• starts — сумма пяти статусов лидов (wait + hold + approve + cancel + trash).
• confirms — равно totals.approve.
• unsubs — равно totals.cancel.
• lefts — равно totals.trash.
• cr — конверсия как доля от 0 до 1 (approve / starts), без умножения на 100 и без округления (например, 0.84). Если starts равно 0, cr равно 0.

Временной ряд по дням

GET /api/stats/series.json

Счётчики по дням для построения графиков. Принимает те же фильтры, что и сводная статистика.

{
  "status": "ok",
  "series": [
    { "date": "2026-05-20", "wait": 5, "hold": 1, "approve": 19, "cancel": 2, "trash": 0, "org_join": 8, "org_leave": 3 },
    { "date": "2026-05-21", "wait": 4, "hold": 0, "approve": 15, "cancel": 1, "trash": 1, "org_join": 5, "org_leave": 2 }
  ],
  "group": "day"
}

series — массив точек (по одной на день; пустой [], если данных нет); каждая точка содержит дату и те же семь счётчиков, что и totals в сводке. group всегда равно "day". Дни без активности пропускаются. Как и сводка, ряд считается в реальном времени из актуальных данных (лиды — по текущему статусу) и кешируется на несколько минут.

Топ кампаний

GET /api/stats/campaigns.json

Рейтинг кампаний по эффективности за период — панель «Топ кампаний» в дашборде. Считает лидов по каждой неудалённой кампании аккаунта и сортирует по числу подтверждённых подписчиков (approve), затем по starts, затем по ID. Как и сводка, считается в реальном времени из актуальных данных (лиды — по текущему статусу) и кешируется на несколько минут; органика в рейтинге не участвует.

{
  "status": "ok",
  "data": [
    {
      "id": 12,
      "name": "Spring promo",
      "code": "abc123",
      "chat_title": "My Channel",
      "wait": 50,
      "hold": 12,
      "approve": 420,
      "cancel": 35,
      "trash": 23,
      "starts": 540,
      "cr": 0.7777777777777778
    }
  ]
}

data — массив кампаний, отсортированный по убыванию approve, затем starts, затем по возрастанию ID и обрезанный до limit. Для каждой кампании: wait, hold, approve, cancel, trash — счётчики по статусам лидов; starts — их сумма; cr — конверсия как доля от 0 до 1 (approve / starts), как и в сводке. Отдельного фильтра по кампании здесь нет — рейтинг строится по всем неудалённым кампаниям аккаунта.

Сводный отчёт

GET /api/stats/report.json

Группированная таблица статистики — экран «Статистика» в дашборде. Считает запуски и лидов по статусам (из актуальных данных, лиды — по текущему статусу) плюс активность в чате (вступления, выходы, баны), сгруппированные по выбранному измерению.

{
  "status": "ok",
  "group": "date",
  "traffic": "all",
  "rows": [
    {
      "key": "2026-06-20",
      "label": "2026-06-20",
      "total": 540,
      "valid": 517,
      "wait": 50,
      "hold": 12,
      "approve": 420,
      "cancel": 35,
      "trash": 23,
      "cr": 0.7777777777777778,
      "validity": 0.9574074074074074,
      "joins": 95,
      "leaves": 18,
      "bans": 4
    }
  ],
  "totals": {
    "key": "",
    "label": "",
    "total": 540,
    "valid": 517,
    "wait": 50,
    "hold": 12,
    "approve": 420,
    "cancel": 35,
    "trash": 23,
    "cr": 0.7777777777777778,
    "validity": 0.9574074074074074,
    "joins": 95,
    "leaves": 18,
    "bans": 4
  }
}

rows отсортированы по дате (от новых к старым), а для группировки по кампании/боту — по убыванию total, затем approve, затем по ID. totals — те же метрики, просуммированные по всем строкам (поля key/label пустые).

Сводный отчёт в CSV

GET /api/stats/report.csv

Те же данные, что и сводный отчёт, с теми же параметрами (group/traffic/from/to/bots/campaigns), в виде файла CSV для скачивания. Ответ — text/csv; charset=utf-8 c UTF-8 BOM и заголовком Content-Disposition: attachment; filename="stats-ГГГГММДД.csv".

Первый столбец — измерение группировки (date, campaign или bot; для группировки по кампании добавляется столбец code), далее total,valid,wait,hold,approve,cancel,trash,cr,validity,joins,leaves,bans. Последняя строка — итоговая (total) с суммами по всем группам.