Массовая рассылка

MaxBotStat умеет отправлять одно и то же сообщение всем контактам бота — текстом или с медиа.

Через кабинет

1. Откройте бота → Рассылки → Создать.
2. Введите текст (до 4000 символов).
3. По желанию прикрепите файл:
   • photo — JPG/PNG до 20 MB;
   • audio — MP3/M4A до 20 MB;
   • file — любой файл до 20 MB.
4. Выберите платформу: all, tg (только Telegram-боты), max (только Max).
5. Нажмите Отправить.

После запуска вы увидите счётчик: отправлено / не доставлено / всего. Каждое исходящее сообщение записывается в БД с direction='out'.

Ограничения и лимиты

Telegram имеет жёсткие лимиты на отправку:

• 30 сообщений в секунду на одного бота для разных пользователей.
• 20 сообщений в минуту в одну группу.
• При превышении — 429 Too Many Requests с заголовком Retry-After.

MaxBotStat не разгоняет рассылку искусственно: отправляем последовательно, пишем в failed_count каждый отказ. На 5000 контактов рассылка займёт несколько минут.

WARNING

Если бот заблокирован пользователем (Forbidden: bot was blocked by the user) — это считается failed. Контакт остаётся в БД, но при следующих рассылках он снова будет считаться неактивным получателем.

Через REST API

curl -X POST "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/broadcast" \
     -H "X-API-Key: mbs_..." \
     -H "Content-Type: application/json" \
     -d '{"text":"Привет! Скидка 20% по промокоду SPRING до конца недели."}'

Ответ:

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

Эндпоинт синхронный — вернётся, когда отправит всем. Для больших аудиторий используйте кабинет: там UI показывает прогресс.

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

Чтобы не повторить рассылку при ретрае, на стороне клиента храните id ответа. Повторный вызов создаст новую рассылку — система не дедуплицирует автоматически.

Сегментация

В кабинете можно ограничить аудиторию:

• по UTM-источнику;
• по intent'у;
• по дате последнего сообщения (например, «активные за 30 дней»).

В REST API v1 рассылка идёт по всем контактам бота. Для сегментов используйте кабинет.

Отчёты

Все рассылки сохраняются в таблицу broadcasts:

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

Этикет

• Не шлите одно и то же сообщение чаще раза в неделю — растёт failed_count.
• Используйте intent-сегменты, чтобы попадать в релевантную аудиторию.
• Не отправляйте холодным контактам — Telegram активно банит ботов с массовым спамом.