Кампании, экраны и медиа

Полное управление кампаниями (CRUD, диплинк, пауза/возобновление), интеграция с трекером (поток и его статистика), триггерные дожимы, многоэкранные приветственные сценарии с кнопками, CAS-защита, чистка групп и загрузка медиа.

Все эндпоинты на этой странице требуют активной подписки (см. Авторизация и соглашения). При истёкшей подписке возвращается unpaid, при неверной авторизации — key. Ответ всегда приходит с кодом HTTP 200 и телом application/json; успех или ошибка указываются в поле status. Общие правила — в разделе Авторизация и соглашения.

Список кампаний

GET /api/camp/list.json

Возвращает все неудалённые кампании (статус кампании ≠ 2) текущего аккаунта, новые первыми. Каждая кампания — полная карточка с пожизненными счётчиками и (если поток создан) разрешённым URL потока трекера.

{
  "status": "ok",
  "data": [
    {
      "id": 12,
      "code": "a1b2c3d4",
      "bot": 7,
      "bot_username": "mytrackbot",
      "chat": -1001234567890,
      "chat_type": 0,
      "chat_title": "My Channel",
      "chat_about": "Эксклюзивный контент для подписчиков",
      "chat_link": "https://t.me/mychannel",
      "name": "Летняя кампания",
      "text": "Подпишитесь на *{title}* — эксклюзив внутри!",
      "media": "",
      "media_type": 0,
      "button": "Получить доступ",
      "link": "https://example.com/lander?click={click}",
      "mode": 0,
      "cas_ban": 0,
      "auto_accept": 0,
      "pb_wait": "",
      "pb_hold": "",
      "pb_approve": "",
      "pb_cancel": "",
      "pb_trash": "",
      "unsub_window": 2592000,
      "track_organic": 1,
      "notify_level": 1,
      "flow_id": 0,
      "flow_url": "",
      "status": 0,
      "created": 1746860400,
      "counters": {
        "wait": 120,
        "hold": 30,
        "approve": 98,
        "cancel": 8,
        "trash": 4,
        "org_join": 15,
        "org_leave": 3
      }
    }
  ]
}

Получить одну кампанию

GET /api/camp/get.json

Возвращает карточку одной кампании по id (та же структура, что в списке) с пожизненными счётчиками и разрешённым URL потока.

{
  "status": "ok",
  "data": {
    "id": 12,
    "code": "a1b2c3d4",
    "bot": 7,
    "bot_username": "mytrackbot",
    "chat": -1001234567890,
    "chat_type": 0,
    "chat_title": "My Channel",
    "chat_about": "Эксклюзивный контент для подписчиков",
    "chat_link": "https://t.me/mychannel",
    "name": "Летняя кампания",
    "text": "Подпишитесь на *{title}* — эксклюзив внутри!",
    "media": "",
    "media_type": 0,
    "button": "Получить доступ",
    "link": "https://example.com/lander?click={click}",
    "mode": 0,
    "cas_ban": 0,
    "auto_accept": 0,
    "pb_wait": "",
    "pb_hold": "",
    "pb_approve": "",
    "pb_cancel": "",
    "pb_trash": "",
    "unsub_window": 2592000,
    "track_organic": 1,
    "notify_level": 1,
    "flow_id": 0,
    "flow_url": "",
    "status": 0,
    "created": 1746860400,
    "counters": {
      "wait": 120,
      "hold": 30,
      "approve": 98,
      "cancel": 8,
      "trash": 4,
      "org_join": 15,
      "org_leave": 3
    }
  }
}

Пустые поля pb_* означают, что кампания наследует глобальные шаблоны постбэков. unsub_window — в секундах; 0 означает, что окно никогда не закрывается (постбэки cancel/trash отправляются всегда, независимо от времени отписки).

Создать кампанию

POST /api/camp/add.json

Создаёт кампанию на принадлежащем вам, не удалённом боте и чате. Применяется лимит кампаний вашего тарифа (-1 = безлимит). Название и тип чата подтягиваются из кеша админ-чатов бота; код из 8 символов генерируется автоматически.

bot и chat должны быть получены из bots/chats — это бот-администратор и чат, в котором он состоит.

{ "status": "ok", "id": 12, "code": "a1b2c3d4" }

При создании название, описание и публичная ссылка чата подтягиваются из Telegram (не критично — при недоступности заполняются позже) и сохраняются в карточку (chat_title, chat_about, chat_link).

Изменить кампанию

POST /api/camp/edit.json

Частичное обновление: изменяются только переданные поля, остальные остаются как есть. Каждое поле, включая каждый из pb_*, редактируется независимо. Бот и чат после создания изменить нельзя. Изменение media сбрасывает закешированный file_id Telegram (файл будет загружен заново при следующем /start).

{ "status": "ok" }

Получить диплинк

GET /api/camp/link.json

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

{
  "status": "ok",
  "code": "a1b2c3d4",
  "url": "https://t.me/mytrackbot?start=a1b2c3d4-{click}",
  "tracker_connected": true
}

В ссылке всегда присутствует литеральный макрос {click} — трекер рекламодателя подставляет реальный click ID в момент перехода. tracker_connected показывает, подключён ли у вас трекер (можно ли создать поток через camp/flow).

Поставить на паузу или возобновить

POST /api/camp/pause.json

{ "status": "ok", "camp_status": 1 }

camp_status — новый статус кампании в ответе: 1 на паузе, 0 активна.

Удалить кампанию

POST /api/camp/del.json

Мягко удаляет кампанию (статус кампании = 2). Существующие лиды, записи журнала и статистика сохраняются и продолжают ссылаться на кампанию.

{ "status": "ok" }

Переключить режим приветствия

POST /api/camp/mode.json

Переключает приветственный сценарий между классическим одним сообщением (mode = 0) и многоэкранным сценарием (mode = 1). Первое включение режима экранов создаёт стартовый экран из классического креатива (текст/медиа + CTA-кнопка), так что переход не теряет данные и сразу пригоден к работе.

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

{ "status": "ok", "mode": 1 }

Создать поток трекера

POST /api/camp/flow.json

Создаёт поток (flow) в подключённом трекере AlterCPA Lite для диплинка кампании, сохраняет ID и URL потока в кампанию и возвращает URL. Если поток уже создан — возвращает сохранённый URL, не обращаясь к трекеру. Требуется подключённый трекер (см. подключение трекера).

{ "status": "ok", "url": "https://track.example.com/abcd1234" }

Если вызов создания потока в трекере не удался, ответ остаётся status: ok, но содержит мягкую ошибку:

{ "status": "ok", "error": "create" }

Пересинхронизировать поток

POST /api/camp/flowsync.json

Восстанавливает связь кампании с потоком трекера, если поток мог быть удалён на стороне трекера. Проверяет сохранённый поток: если он на месте — обновляет URL и возвращает recreated: false; если трекер сообщает, что поток удалён — пересоздаёт его из диплинка кампании, сохраняет новый ID и URL и возвращает recreated: true. Если трекер недоступен, поток не пересоздаётся (чтобы не плодить дубликаты). Используйте этот вызов для восстановления потока, удалённого на стороне трекера.

{ "status": "ok", "url": "https://track.example.com/abcd1234", "recreated": false }

Мягкие ошибки приходят с status: ok и полем error:

{ "status": "ok", "error": "sync" }

Статистика потока

GET /api/camp/flowstats.json

Возвращает дневную статистику из подключённого трекера для потока кампании за последние N дней.

{
  "status": "ok",
  "rows": [
    {
      "date": "2026-06-20",
      "clicks": 540,
      "unique": 512,
      "wait": 120,
      "hold": 30,
      "approve": 98,
      "cancel": 8,
      "trash": 4,
      "cr": 19.14,
      "ar": 81.67,
      "exit_pct": 10.91
    }
  ]
}

Если у кампании ещё нет потока, rows пуст ([]). При сбое запроса к трекеру ответ остаётся status: ok с мягкой ошибкой {"status":"ok","error":"stats"}.

Триггерные дожимы: получить

GET /api/camp/broadcast.json

Возвращает пять блоков триггерных авто-сообщений кампании — по одному на каждый статус лида (0 wait, 1 hold, 2 approve, 3 cancel, 4 trash). Статус без сохранённого блока возвращается как нулевой блок (on = 0). Это триггерные дожимы по статусу; массовые ручные рассылки описаны на странице Рассылки.

{
  "status": "ok",
  "data": [
    {
      "status": 0,
      "on": 1,
      "delay": 3600,
      "text": "Ещё думаете? Доступ закрывается!",
      "media": "",
      "media_type": 0,
      "button": "Вступить",
      "link": "https://t.me/mytrackbot?start=a1b2c3d4-{click}"
    }
  ]
}

Триггерные дожимы: сохранить

POST /api/camp/broadcast.json

Сохраняет (upsert) один блок дожима по статусу. Включение (on = 1) требует функции рассылок на вашем тарифе; выключение и редактирование выключенного блока разрешены всегда. Изменение media сбрасывает закешированный file_id.

{ "status": "ok" }

Тест дожима

POST /api/camp/btest.json

Ставит в очередь «отправку себе» — превью блока дожима (только текст + CTA) владельцу через служебного бота. Блок должен быть предварительно сохранён.

{ "status": "ok" }

Приветственные экраны: список

GET /api/screen/list.json

Возвращает экраны кампании (стартовый первым; сортировка по scr_order, scr_id), каждый со своими упорядоченными кнопками. Доступ только владельцу; функцией экранов не ограничен (но требует активной подписки).

Многоэкранный сценарий используется кампанией при режиме кампании mode = 1 (см. режим приветствия). Экран — это медиа + текст + упорядоченный список inline-кнопок, которые бот раскладывает по строкам шириной columns.

{
  "status": "ok",
  "data": [
    {
      "id": 30,
      "campaign": 12,
      "order": 0,
      "name": "Старт",
      "text": "Привет! Готовы вступить?",
      "media": "",
      "media_type": 0,
      "columns": 1,
      "created": 1746860400,
      "buttons": [
        { "id": 51, "order": 0, "label": "Подробнее", "kind": 1, "link": "", "target": 31 },
        { "id": 52, "order": 1, "label": "Открыть сайт", "kind": 0, "link": "https://example.com/lander", "target": 0 }
      ]
    }
  ]
}

Добавить экран

POST /api/screen/add.json

Добавляет экран в кампанию (лимит screens_max, по умолчанию 10). Первый экран получает order 0 (стартовый). Возвращает новую карточку экрана.

{
  "status": "ok",
  "data": {
    "id": 32,
    "campaign": 12,
    "order": 2,
    "name": "Бонус",
    "text": "Дарим бонус новым подписчикам",
    "media": "",
    "media_type": 0,
    "columns": 1,
    "buttons": [],
    "created": 0
  }
}

Изменить экран

POST /api/screen/edit.json

Частичное обновление содержимого экрана: изменяются только переданные поля. Изменение media сбрасывает закешированный file_id. Требует функции экранов на тарифе.

{ "status": "ok" }

Копировать экран

POST /api/screen/copy.json

Дублирует экран (текст + медиа + кнопки) и добавляет копию в ту же кампанию (лимит screens_max). Навигационные кнопки сохраняют свой target. Требует функции экранов.

{
  "status": "ok",
  "data": {
    "id": 33,
    "campaign": 12,
    "order": 3,
    "name": "Старт",
    "text": "Привет! Готовы вступить?",
    "media": "",
    "media_type": 0,
    "columns": 1,
    "buttons": [
      { "id": 60, "order": 0, "label": "Открыть сайт", "kind": 0, "link": "https://example.com/lander", "target": 0 }
    ],
    "created": 1750000000
  }
}

Если не удалось перечитать копию из БД, ответ — резервный {"status":"ok","id":33} (только id, без data).

Удалить экран

POST /api/screen/del.json

Удаляет экран и его кнопки. Отказывает, если это единственный экран кампании или если на него ещё ведёт навигационная кнопка. Требует функции экранов.

{ "status": "ok" }

Переупорядочить экраны

POST /api/screen/reorder.json

Переназначает порядок экранов по списку их ID. Экран на позиции 0 становится стартовым. ID, не принадлежащие кампании, молча пропускаются. Требует функции экранов.

{ "status": "ok" }

Тест экрана

POST /api/screen/test.json

Отправляет «себе» превью экрана (только текст + кнопки; медиа опускается) владельцу через служебного бота. Доступ только владельцу; функцией экранов не ограничен.

{ "status": "ok" }

Добавить кнопку

POST /api/button/add.json

Добавляет кнопку на экран (лимит screen_buttons_max, по умолчанию 8). kind, link и target валидируются совместно. Требует функции экранов. Возвращает новую карточку кнопки.

{
  "status": "ok",
  "data": { "id": 61, "order": 1, "label": "Подробнее", "kind": 1, "link": "", "target": 31 }
}

Изменить кнопку

POST /api/button/edit.json

Полностью заменяет label/kind/link/target кнопки (не частичное обновление — все поля переписываются как единое целое). kind/link/target валидируются совместно, как при добавлении. Требует функции экранов.

{ "status": "ok" }

Удалить кнопку

POST /api/button/del.json

Удаляет кнопку. Требует функции экранов.

{ "status": "ok" }

Переупорядочить кнопки

POST /api/button/reorder.json

Переназначает порядок кнопок одного экрана по списку их ID. ID, не принадлежащие экрану, молча пропускаются. Требует функции экранов.

{ "status": "ok" }

CAS-защита

POST /api/camp/cas.json

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

{ "status": "ok", "cas_ban": 1 }

Запустить чистку группы

POST /api/camp/clean.json

Запускает чистку группы: собирает наблюдаемую базу участников (вступившие лиды, оставшиеся в чате ∪ участники из журнала, числящиеся как присутствующие) в очередь и ставит задачу, которую разбирает наш бэкенд. Одновременно может идти только одна чистка на кампанию. Требует функции экранов на вашем тарифе.

{ "status": "ok", "clean_id": 5, "total": 842, "state": 0 }

Если проверять некого, задача завершается сразу: {"status":"ok","clean_id":5,"total":0,"state":1}.

Статус чистки

GET /api/camp/clean.json

Возвращает последнюю задачу чистки кампании для опроса прогресса. Чтение статуса функцией экранов не ограничено (в отличие от запуска чистки).

Если чистка никогда не запускалась:

{ "status": "ok", "exists": false }

Если задача есть:

{
  "status": "ok",
  "exists": true,
  "state": 0,
  "total": 842,
  "checked": 310,
  "kicked_cas": 4,
  "kicked_dead": 12,
  "failed": 1,
  "started": 1750000000,
  "finished": 0
}

Загрузить медиа

POST /api/media/upload.json

Загружает изображение или видео для приветственного сообщения кампании, экрана, дожима или рассылки. Возвращает ссылку на медиа и код типа для сохранения через camp/add, camp/edit, screen/* и т. д.

Отправляйте как multipart/form-data, файл — в поле file. Допустимые форматы: jpg, jpeg, png, webp, gif (фото) и mp4, mov, webm (видео); документы не принимаются. Размер ограничен (по умолчанию ~20 МиБ). Лимит — 20 загрузок в час на аккаунт.

{ "status": "ok", "media": "17/abc123.jpg", "media_type": 1 }

media — путь относительно медиа-каталога (его и нужно сохранять в кампанию/экран). media_type — код типа: 1 фото, 2 видео; передавайте его вместе с media.