REST API → Рассылка

POST /api/v1/bots/{id}/broadcast

Отправляет текстовое сообщение всем контактам бота. Запрос синхронный — возвращается, когда последний пользователь обработан.

Scope: write

Тело запроса

{ "text": "Привет! Скидка 20% по промокоду SPRING до конца недели." }

Поле	Тип	Описание
text	string	до 4000 символов

Запрос

curl -X POST "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/broadcast" \
     -H "X-API-Key: $MBS_KEY" \
     -H "Content-Type: application/json" \
     -d '{"text":"Привет!"}'

Ответ

{
  "id": "8c3a...",
  "total_count": 412,
  "sent_count": 408,
  "failed_count": 4,
  "created_at": "2026-04-30T12:00:00Z"
}

Поле	Описание
id	публичный UUID рассылки в broadcasts
total_count	сколько контактов было выбрано (= все контакты бота)
sent_count	сколько успешно доставлено
failed_count	сколько не доставлено (заблокировали бота, ошибка Telegram, недоступная сеть)
created_at	время старта

Поведение

• На каждого получателя — отдельный вызов Telegram sendMessage или Max POST /messages.
• Отправляется последовательно (без распараллеливания), чтобы не получить 429 от Telegram.
• При сбое к одному получателю остальные не пострадают — failed_count инкрементируется, цикл продолжается.
• В messages таблицу записывается каждое успешно отправленное сообщение (direction='out').

Сегментация в API нет

POST /broadcast шлёт всем контактам бота. Для сегментов:

• используйте кабинет (UI поддерживает фильтры по UTM, intent, дате);
• или сделайте свою сегментацию: получите список контактов через /api/v1/bots/{id}/contacts, отфильтруйте на своей стороне, шлите по одному через /send.

Ошибки

HTTP	Сообщение	Что значит
400	text required	пустое тело
400	text too long (max 4000 chars)	текст длиннее лимита Telegram
400	Broadcast requires bot token	бот добавлен без токена — отправлять некому
403	scope mismatch	ключ без write
404	Bot not found	бот не ваш или не существует

Тайм-аут

Запрос может выполняться долго — на 5000 контактов это ~3 минуты. Учитывайте это:

• curl --max-time 600 чтобы не закрыло раньше;
• в Node.js — signal: AbortSignal.timeout(600_000);
• в Python requests — timeout=600.

Если ваш HTTP-клиент отвалится по тайм-ауту, рассылка продолжит идти на сервере — статус можно посмотреть в кабинете в разделе Рассылки.

Лимиты Telegram

Ограничение	Значение
Сообщений в секунду одному получателю	1
Сообщений в секунду разным получателям	30
Сообщений в минуту в одну группу	20

При превышении — 429 Too Many Requests с заголовком Retry-After. MaxBotStat учитывает это и не разгоняет цикл искусственно.

Идемпотентность

Сервер не дедуплицирует рассылки. Если вы дважды нажмёте POST /broadcast с одним и тем же текстом — пользователи получат два сообщения. Защититесь:

• сохраняйте id ответа на стороне клиента;
• не повторяйте POST на 5xx — Telegram уже принял сообщения, повтор приведёт к дублям.

Аналитика рассылки

id ответа можно использовать для аудита через приватный API кабинета (/api/bots/:id/broadcasts). В REST v1 пока нет ручки для просмотра прошлых рассылок — добавим в v1.1.