Zapnoty — Broadcast — массовая рассылка

Документация API

REST API для уведомлений через Telegram и Max. Подписчики, OTP, рассылки, формы, helpdesk.

Broadcast (массовая рассылка)

Отправка сообщения всем подписчикам или сегменту.

POST /v1/broadcast

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

text string обязательный

Текст сообщения

format string

Формат текста: plain (по умолчанию), markdown или html

media object

Объект медиа: {type, url}. Типы: photo, video, document

buttons array

Массив рядов кнопок: [[{text, url}]] или [[{text, callback_data}]]

permission string

Фильтр по permission

tags array

Фильтр по тегам: ["vip", "beta"]

tags_all array

AND-фильтр: подписчик должен иметь ВСЕ перечисленные теги

tags_any array

OR-фильтр: подписчик должен иметь хотя бы один из тегов

exclude_tags array

Исключить подписчиков с любым из этих тегов

exclude_permissions array

Исключить подписчиков с любым из этих разрешений

messages_per_minute number

Ограничение скорости (сообщений/мин). По умолчанию — максимально по квоте бота

dry_run boolean

true — предпросмотр без отправки: вернёт аудиторию, кредиты и пример сообщения

POST /v1/broadcast
 
{
"text": "Версия 2.0 доступна!",
"permission": "updates",
"tags": ["beta"]
}

Ответ

{
"job_id": "a1b2c3d4-e5f6-...",
"status": "pending",
"total_subscribers": 1500
}

Предпросмотр (dry-run)

С dry_run: true рассылка не создаётся — возвращается оценка аудитории, кредитов и пример отрендеренного сообщения. Удобно проверить фильтры перед отправкой.

POST /v1/broadcast
 
{
"text": "Скидка 20% для VIP",
"tags_all": ["vip"],
"exclude_tags": ["unsubscribed_promo"],
"dry_run": true
}

Ответ

{
"dry_run": true,
"would_send_to": 342,
"estimated_credits": 342,
"rendered_sample": "Скидка 20% для VIP",
"filters_applied": { ... }
}

GET /v1/broadcast/:job_id

Получение статуса рассылки.

Поля ответа: status (pending/processing/completed/failed/cancelled), total, sent, failed, skipped.

{
"job_id": "b7f3...",
"status": "completed",
"total": 2847,
"sent": 2835,
"failed": 12,
"skipped": 0
}

DELETE /v1/broadcast/:job_id

Останавливает рассылку. Уже отправленные сообщения остаются, новые не идут. Воркер замечает отмену на следующей итерации; по завершении шлёт webhook broadcast.cancelled.

GET /v1/broadcast/:job_id/deliveries

Детальный отчёт о доставке по подписчикам. Параметры: status (success/failed), limit (до 500), cursor (для пагинации — значение next_cursor из предыдущего ответа).

GET /v1/broadcast/{job_id}/deliveries?status=failed
 
{
"deliveries": [
{ "channel": "telegram", "chat_id": 123, "status": "failed", "error": "bot blocked" }
],
"next_cursor": "2026-05-20T10:00:00Z"
}

Frequency cap

Project-level лимит маркетинговых сообщений на подписчика (в день / в неделю). Настраивается в кабинете на вкладке «Рассылки». По умолчанию выключен. При рассылке подписчики с превышением лимита пропускаются (поле skipped в статусе).

Связанные разделы

Быстрый старт
Первое сообщение за 2 минуты: получение ключа, deep link для подписки, отправка через curl.
Аутентификация
Как авторизовать запросы к API через Authorization: Bearer zn_… ключ проекта.
POST /v1/send — отправка
Отправка персональных уведомлений: текст, HTML/Markdown, медиа, кнопки, шаблоны.