Рассылки

Настройка триггерных дожимов по статусам кампании и создание и запуск ручных массовых рассылок. Концепции — в руководстве по рассылкам; эта страница — справочник по API.

Все эндпоинты рассылок требуют активной оплаченной сессии (иначе error: unpaid). Функцию рассылки на тарифе проверяют только действия, создающие отправки: add, edit, start ручных рассылок и включение триггерного блока (on=1) — без неё они вернут error: broadcasts. Просмотр и сворачивание уже существующих рассылок (list, quota, get, pause, resume, reset, cancel, del, test) функции не требуют, поэтому при понижении тарифа существующие рассылки можно доглядеть и аккуратно завершить.

Все ответы — HTTP 200 с application/json; успех или ошибка указаны в теле. Время — unix-секунды (0 = не задано).

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

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": 1800,
      "text": "Добро пожаловать! Жмите кнопку ниже 👇",
      "media": "", "media_type": 0,
      "button": "Открыть", "link": "https://example.com/l?click={click}" },
    { "status": 1, "on": 0, "delay": 0, "text": "", "media": "", "media_type": 0, "button": "", "link": "" },
    { "status": 2, "on": 0, "delay": 0, "text": "", "media": "", "media_type": 0, "button": "", "link": "" },
    { "status": 3, "on": 0, "delay": 0, "text": "", "media": "", "media_type": 0, "button": "", "link": "" },
    { "status": 4, "on": 0, "delay": 0, "text": "", "media": "", "media_type": 0, "button": "", "link": "" }
  ]
}

delay — в секундах после попадания лида в статус. media_type: 0 нет, 1 фото, 2 видео.

Сохранить один блок

POST /api/camp/broadcast.json

Создаёт или обновляет блок одного статуса.

{ "status": "ok" }

Включение блока (on=1) требует функции рассылок → иначе error: broadcasts. Выключение или правка уже выключенного блока разрешены всегда (чтобы при понижении тарифа блок можно было выключить). Смена медиа сбрасывает кэшированный file_id.

Отправить блок себе

POST /api/camp/btest.json

Доставляет превью одного сохранённого блока статуса в Telegram авторизованного пользователя через сервисного бота (только текст и кнопка — медиа не включается).

{ "status": "ok" }

Список рассылок

GET /api/broadcast/list.json

Возвращает ручные рассылки пользователя, новые сверху, со сохранёнными счётчиками. Статусы рассылки: 0 черновик · 1 идёт · 2 готово · 3 отменена · 4 пауза.

Параметров нет. Каждая карточка содержит полный набор полей (тот же, что у get), но без живого пересчёта: remaining всегда 0, total — сохранённое значение, а campaigns — null (список кампаний заполняет только get).

{
  "status": "ok",
  "data": [
    {
      "id": 5,
      "name": "Майский возврат",
      "status": 1,
      "statuses": 24,
      "campaigns": null,
      "created_from": 0, "created_to": 0,
      "status_from": 1714521600, "status_to": 1717113600,
      "text": "Мы скучаем — держите скидку 20% 🎁",
      "media": "", "media_type": 0,
      "button": "Забрать", "link": "https://example.com/back?click={click}",
      "total": 1240, "remaining": 0,
      "queued": 440, "sent": 800, "failed": 0,
      "started": 1717500000, "created": 1717490000
    }
  ]
}

statuses — битовая маска целевых статусов лида (бит 0 wait … бит 4 trash); 24 = биты 3+4 = cancel + trash.

Шкала дневного лимита

GET /api/broadcast/quota.json

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

{ "status": "ok", "data": { "cap": 500, "used": 120, "queued": 440 } }

Получить одну рассылку

GET /api/broadcast/get.json

Возвращает рассылку целиком, включая область кампаний и фильтры. Для незапущенной рассылки (не в статусе идёт) пересчитывает total (живая аудитория) и remaining (размер Доделать — лиды, ещё не охваченные). Для идущей рассылки сохранённые счётчики оставлены как есть.

{
  "status": "ok",
  "data": {
    "id": 5, "name": "Майский возврат", "status": 2, "statuses": 24,
    "campaigns": [12, 18],
    "created_from": 0, "created_to": 0,
    "status_from": 1714521600, "status_to": 1717113600,
    "text": "Мы скучаем — держите скидку 20% 🎁",
    "media": "", "media_type": 0,
    "button": "Забрать", "link": "https://example.com/back?click={click}",
    "total": 1300, "remaining": 60,
    "queued": 0, "sent": 1240, "failed": 0,
    "started": 1717500000, "created": 1717490000
  }
}

campaigns нормализуется к [] (никогда не null); пустой список = все ваши кампании.

Создать черновик

POST /api/broadcast/add.json

Создаёт пустой черновик рассылки. Требует функции рассылок. На пользователя действует мягкий лимит в 100 рассылок: при достижении вернётся error: limit — удалите ненужную, чтобы освободить место.

{ "status": "ok", "id": 5 }

id приходит верхним полем рядом со status, не внутри data.

Изменить рассылку

POST /api/broadcast/edit.json

Заменяет поля рассылки и область кампаний. Требует функции рассылок. Разрешено в любом состоянии — тело берётся в момент отправки, поэтому правка идущей рассылки влияет на ещё не ушедшие сообщения. Ссылка проверяется на корректность, а медиа — на принадлежность вам; иначе error: func.

{ "status": "ok" }

Запуск (всегда «доделать»)

POST /api/broadcast/start.json

Ставит аудиторию в очередь и переводит рассылку в идёт. Требует функции рассылок. Это всегда доделать: в очередь попадают только лиды, которых рассылка ещё не охватила, поэтому повторный запуск готово/отменена рассылки уйдёт только новым лидам. Разрешено из черновик/готово/отменена; рассылка в состоянии идёт/пауза вернёт error: state.

{ "status": "ok", "queued": 60 }

queued приходит верхним полем — число поставленных в очередь сообщений. 0 означает, что охватывать было некого, и статус рассылки не меняется:

{ "status": "ok", "queued": 0 }

Пауза

POST /api/broadcast/pause.json

идёт → пауза: неотправленные сообщения паркуются и сохраняются (отправщик их пропускает, но не теряет).

{ "status": "ok" }

Продолжить

POST /api/broadcast/resume.json

пауза → идёт: запаркованные сообщения снова становятся актуальными, и отправка продолжается ровно с места остановки.

{ "status": "ok" }

Сбросить

POST /api/broadcast/reset.json

Очищает множество охваченных лидов и счётчики и возвращает черновик/готово/отменена рассылку в черновик, сохраняя название, фильтры и тело. Следующий запуск тогда переотправит всей аудитории. Рассылку в состоянии идёт/пауза нужно сначала отменить.

{ "status": "ok" }

Остановить (отмена)

POST /api/broadcast/cancel.json

идёт/пауза → отменена: сбрасывает остаток сообщений в очереди. Множество уже охваченных лидов сохраняется, поэтому будущий запуск Доделать им не напишет повторно.

{ "status": "ok" }

Удалить

POST /api/broadcast/del.json

Удаляет рассылку и её область, очередь и записи об охвате. Рассылку пауза удалить можно (её запаркованные сообщения уходят вместе с ней); заблокировано только состояние идёт — её сначала нужно отменить.

{ "status": "ok" }

Отправить себе

POST /api/broadcast/test.json

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

{ "status": "ok" }

Ошибки