Эндпоинты лидов, журнала и статистики

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

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

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

Код	Название	Значение
`0`	wait	Подписчик открыл ссылку бота, но ещё не вступил в чат
`1`	hold	Отправил заявку на вступление, ожидает одобрения администратора
`2`	approve	Вступил в чат (или заявка была одобрена)
`3`	cancel	Покинул чат добровольно
`4`	trash	Исключён или забанен в чате

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

Список лидов

GET /api/leads/list.json

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

Параметр	Описание
`campaign`	Фильтр по ID кампании
`status`	Фильтр по коду статуса лида (0–4)
`from`	Начало диапазона дат (Unix timestamp)
`to`	Конец диапазона дат (Unix timestamp)
`limit`	Размер страницы (по умолчанию 50, максимум 200)
`offset`	Смещение для пагинации

{
  "status": "ok",
  "data": [
    {
      "id": 1001,
      "campaign": 12,
      "subscriber": 9876543210,
      "username": "alice",
      "click": "abc456xyz",
      "status": 2,
      "start_time": "2026-05-20 10:00:00",
      "join_time": "2026-05-20 10:01:00",
      "updated": "2026-05-20 10:01:00"
    }
  ],
  "total": 1
}

username — пустая строка, если у подписчика нет username в Telegram. click — пустая строка, если подписчик пришёл без click-payload (например, открыл ссылку бота напрямую, а не через диплинк). join_time равен "0000-00-00 00:00:00", пока лид находится в статусе wait или hold.

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

GET /api/journal/list.json

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

Параметр	Обязательный	Описание
`bot`	✓	ID бота
`chat`	✓	ID чата (Telegram)
`action`		Фильтр по типу действия (см. таблицу ниже)
`from`		Начало диапазона дат (Unix timestamp)
`to`		Конец диапазона дат (Unix timestamp)
`limit`		Размер страницы (по умолчанию 50, максимум 200)
`offset`		Смещение для пагинации

{
  "status": "ok",
  "data": [
    {
      "id": 5001,
      "subscriber": 9876543210,
      "username": "alice",
      "action": "join",
      "paid": 1,
      "time": "2026-05-20 10:01:00"
    }
  ],
  "total": 1
}

`action`	Значение
`join`	Подписчик вступил в чат
`leave`	Подписчик покинул чат добровольно
`ban`	Подписчик был исключён или забанен
`request`	Подписчик отправил заявку на вступление
`approve`	Заявка на вступление одобрена администратором

paid равен 1, когда событие соответствует отслеживаемому лиду (подписчик запустил бота), и 0 для органической активности.

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

GET /api/stats/summary.json

Агрегированные счётчики по всем кампаниям или одной кампании.

Параметр	Описание
`campaign`	Фильтр по одной кампании (не указывайте для статистики по всему аккаунту)
`from`	Начало диапазона дат (Unix timestamp)
`to`	Конец диапазона дат (Unix timestamp)

{
  "status": "ok",
  "data": {
    "starts": 500,
    "holds": 12,
    "confirms": 420,
    "cancels": 35,
    "trashes": 8,
    "cr": 84.0,
    "organic_joins": 150,
    "organic_leaves": 42
  }
}

cr — конверсия: confirms / starts × 100, округлённая до одного знака после запятой. organic_joins и organic_leaves — активность, не связанная ни с одним лидом.

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

GET /api/stats/series.json

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

Параметр	Описание
`campaign`	Фильтр по одной кампании
`from`	Начало диапазона дат (Unix timestamp)
`to`	Конец диапазона дат (Unix timestamp)

{
  "status": "ok",
  "data": [
    { "date": "2026-05-20", "starts": 22, "confirms": 19, "cancels": 2, "trashes": 0, "organic": 8 },
    { "date": "2026-05-21", "starts": 18, "confirms": 15, "cancels": 1, "trashes": 1, "organic": 5 }
  ]
}

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

Рассылки Передача