Рассылки
Рассылки по базе создаются из кабинета и отправляются фоновым воркером — веб-интерфейс не блокируется, а прогресс виден вживую. История хранит последние 30 рассылок со счётчиками отправленных и ошибок.
Нужен воркер
Отправкой занимается воркер (taskiq). Если воркер не запущен, рассылка останется в статусе pending и никуда не уйдёт.
Создание рассылки
- Выберите аудиторию — рядом с каждым сегментом кабинет показывает живой счётчик получателей.
- Напишите текст (до 4096 символов, поддерживается HTML-разметка Telegram).
- При желании прикрепите медиа и добавьте кнопку.
- Отправьте — рассылка появится в истории и начнёт выполняться.
Рассылка с пустой аудиторией не создастся — кабинет вернёт ошибку audience is empty.
Аудитории
Сегмент определяется статусом текущей подписки пользователя. Во всех случаях берутся только активные пользователи бота (не заблокированные, с Telegram ID).
| Аудитория | Кто попадает |
|---|---|
all | Все пользователи бота |
active | Подписка в статусе ACTIVE или LIMITED (исчерпан трафик) |
trial | Подписка в статусе TRIAL |
expired | Подписка в статусе EXPIRED или DISABLED |
Общее число получателей (total) фиксируется в момент создания рассылки.
Контент
Медиа — четыре типа: text, photo, video, gif (отправляется как анимация, текст становится подписью). Файл сначала загружается через кабинет: до 20 МБ, форматы .jpg / .jpeg / .png / .webp / .gif / .mp4.
Премиум-эмодзи — можно указать emoji_id кастомного эмодзи: он подставится перед текстом через <tg-emoji>; у клиентов без поддержки отобразится обычная ⭐.
Кнопка — одна inline-кнопка под сообщением (текст до 64 символов). Два режима:
| Режим | Что делает |
|---|---|
| URL | Открывает внешнюю ссылку |
| Действие бота | Отправляет пользователя в раздел бота (act:<действие>) — те же действия, что и у кнопок меню, см. Конструктор меню |
Цвет кнопки задаётся HEX-кодом, но Telegram поддерживает только три пресета — код автоматически сводится к ближайшему: преобладает зелёный канал → success, красный → danger, иначе → primary.
Живой прогресс
Статусы рассылки: pending (создана, ждёт воркера) → running → done. Пока рассылка идёт, кабинет опрашивает её состояние и показывает прогресс-бар: воркер коммитит счётчики sent / failed в базу каждые 25 сообщений, поэтому цифры растут прямо на глазах. У завершённой рассылки видны время старта и финиша.
Скорость и лимиты Telegram
Воркер шлёт с паузой 36 мс между сообщениями — примерно 28 сообщений в секунду, с запасом под глобальный лимит Telegram в 30/с. Рассылка на 10 000 получателей занимает около 6 минут.
Если Telegram всё же вернёт flood-wait (TelegramRetryAfter), воркер подождёт указанное время и повторит отправку этому получателю ещё один раз.
Кто попадает в ошибки
Счётчик failed растёт на:
- пользователях, заблокировавших бота (
TelegramForbiddenError); - удалённых/деактивированных аккаунтах;
- повторной неудаче после ожидания flood-wait;
- любой другой ошибке отправки конкретному получателю.
Ошибка по одному получателю не останавливает рассылку — воркер идёт дальше по списку. Заметная доля failed в сегменте all — это нормально: база копит «мёртвые души» из тех, кто заблокировал бота.
Ошибки — это тоже данные
Разница total − sent показывает реальный охват базы. Если хотите оценить живую аудиторию перед платной кампанией — сравните счётчики последней рассылки по all.