Лимиты Telegram Bot API и почему падает наивный for-цикл
Начинающие разработчики часто реализуют рассылку через обычный цикл: выбирают список пользователей из базы данных и поочередно вызывают метод sendMessage. На тестовой базе из сотни контактов такой подход срабатывает мгновенно. Однако на реальной аудитории в несколько тысяч подписчиков наивный скрипт быстро падает или наглухо блокирует весь сервис. Причина кроется в строгих сетевых фильтрах Telegram Bot API.
Telegram защищает свои серверы от спама с помощью жесткого ограничения частоты запросов. Общеизвестные правила просты: бот не должен отправлять более одного сообщения в секунду в один конкретный приватный чат и более примерно 30 сообщений в секунду суммарно по всем чатам. Для групп лимит составляет около 20 сообщений в минуту. При превышении этих порогов Bot API моментально возвращает ошибку и перестает принимать запросы.
Вторая беда прямого цикла — блокирующие сетевые вызовы. Если слать сообщения последовательно, сетевые задержки превратят отправку большой рассылки в многочасовое ожидание. Если запустить тысячи параллельных потоков без ограничений, сервер исчерпает пул сетевых сокетов, а Telegram заблокирует запросы по лимиту частоты. Надежное решение требует отделения постановки задачи от ее исполнения через контролируемый конвейер.
- Лимит на один чат: не более одного сообщения в секунду в конкретный диалог с пользователем.
- Глобальный лимит бота: безопасная планка составляет порядка 25–30 сообщений в секунду суммарно во все чаты.
- Лимит на группы и каналы: около 20 сообщений в минуту в один групповой чат.
- Сетевые сокеты: неконтролируемый параллелизм приводит к исчерпанию файловых дескрипторов операционной системы.
Ошибки 429 retry_after и блокировки 403: правила обработки
При массовой рассылке ошибки неизбежны. Надежная система должна не падать при сбоях, а классифицировать ответы платформы и плавно подстраивать скорость работы. Главный сигнал снижения темпа от Telegram — HTTP-статус 429 Too Many Requests. В теле такого ответа Telegram всегда присылает JSON с полем retry_after, где указано точное число секунд ожидания.
Если воркер получает статус 429, сервис обязан приостановить отправку на указанный интервал с добавлением небольшого случайного смещения (jitter). Попытка продолжить бомбардировку API во время штрафного окна приводит к росту тайм-аута или временной блокировке токена. Воркер должен вернуть задачу обратно в очередь со сдвинутым временем выполнения и продолжить работу с другими задачами.
Вторая критическая группа ошибок — статус 403 Forbidden. Чаще всего Telegram поясняет причину: «bot was blocked by the user» или «user is deactivated». Пользователь остановил бота, заблокировал диалог или удалил свой аккаунт. Повторять отправку в такие чаты бессмысленно. Система обязана сразу зафиксировать статус отписки в базе данных и убрать пользователя из рассылочных списков.
- Код 429 Too Many Requests: прочитать параметр retry_after, приостановить отправку и вернуть задачу в очередь с задержкой.
- Код 403 Forbidden (бот заблокирован): немедленно выставить пользователю флаг is_active = false и зафиксировать время блокировки.
- Код 400 Bad Request (чат не найден или деактивирован): пометить профиль как невалидный и исключить из выборки.
- Код 5xx Server Error: временный сбой серверов Telegram; отправить запрос повторно через экспоненциальную паузу.
- Сетевые таймауты: потеря ответа на стыке соединений требует проверки идемпотентности перед повторной отправкой.
Архитектура очереди и воркеров на Go
Для надежных рассылок мы проектируем асинхронный конвейер на Go. Создание рассылки в панели управления лишь сохраняет кампанию в базе данных. Непосредственная отправка поручается фоновым воркерам, которые вычитывают задачи через персистентную очередь. Детально архитектура таких очередей описана в нашей статье про фоновые задачи и очереди на Go.
Ядро системы состоит из диспетчера, ограничителя скорости (rate limiter) и пула горутин. Диспетчер выбирает пачки получателей из PostgreSQL с блокировкой строк через FOR UPDATE SKIP LOCKED. Это позволяет запускать несколько экземпляров сервиса параллельно без риска повторной отправки одной и той же записи. Вопросы взаимодействия бота с внешними событиями раскрыты в статье вебхук или long polling.
Ограничитель частоты реализуется на алгоритме token bucket или leaky bucket с поддержкой глобального окна на уровне 25–30 тиков в секунду. Воркер запрашивает разрешение у лимитера перед каждым сетевым вызовом. При получении ошибки 429 лимитер централизованно замораживает выдачу токенов на время retry_after, защищая систему от каскадных сбоев.
- База данных как персистентный буфер: статус отправки каждого сообщения хранится на диске и не теряется при перезапуске сервиса.
- Глобальный rate limiter: единый счетчик запросов удерживает суммарную скорость на безопасном уровне 25–30 вызовов в секунду.
- Пул воркеров фиксированного размера: фиксированное число горутин равномерно утилизирует процессор и сетевые соединения.
- Адаптивный бэкофф: паузы между повторными попытками растут экспоненциально, не перегружая API во время сетевых сбоев.
Идемпотентность и защита от повторных сообщений
Худшее, что может случиться при рассылке, — получение пользователем одного и того же рекламного сообщения несколько раз подряд. Это моментально вызывает раздражение, волну жалоб на спам и блокировку бота. Дубликаты возникают при разрыве сетевого соединения: воркер отправил запрос, Telegram его обработал, но ответный пакет с кодом 200 потерялся по таймауту. Если воркер просто повторит попытку, клиент получит дубль.
Метод sendMessage в Telegram Bot API не принимает внешние ключи идемпотентности. Поэтому защита от повторов реализуется на уровне внутренней базы данных. Фундаментальные принципы этой механики мы подробно разобрали в статье про идемпотентность и повторы API. Для рассылок применяется составной уникальный ключ, связывающий идентификатор кампании и id пользователя: campaign_id + user_id.
Каждое сообщение проходит через строгий конечный автомат: pending (в очереди), processing (в обработке), sent (доставлено), failed (ошибка) или blocked (бот заблокирован). Смена статуса на processing фиксируется транзакцией до сетевого вызова. Если процесс аварийно завершился, фоновый монитор находит зависшие задачи и передает их на аккуратную верификацию.
- Уникальный составной ключ: ограничение UNIQUE(campaign_id, user_id) в таблице доставки исключает создание дублирующих заданий.
- Фиксация состояния перед отправкой: статус processing устанавливается строго до выполнения HTTP-запроса к Bot API.
- Сохранение message_id: идентификатор сообщения из ответа Telegram записывается в базу для аналитики, редактирования или удаления поста.
- Мониторинг зависших задач: задачи, оставшиеся в статусе processing дольше порогового времени, требуют проверки перед повторным запуском.
Сегментация подписчиков и учет часовых поясов
Отправка одинаковых сообщений всей аудитории превращает полезного бота в источник спама и снижает конверсию. Качественная массовая рассылка телеграм бот всегда опирается на сегментацию подписчиков. Чем релевантнее сообщение потребностям конкретной группы клиентов, тем выше отклик и ниже процент отписок.
Аудиторию сегментируют по языку, городу, давности активности и истории покупок. Если пользователь прямо сейчас оформляет заказ или ведет диалог с консультантом, маркетинговую рассылку отправлять нельзя, иначе она собьет сценарий диалога. Как правильно изолировать состояния пользователей в боте, мы объясняли в материале состояние диалога бота.
Особое внимание уделяется часовым поясам. Уведомление со звуком среди ночи гарантированно приведет к жалобе и блокировке. В профиле подписчика сохраняется часовой пояс (полученный из веб-приложения, геолокации или настроек). Диспетчер рассылки отправляет сообщения только в комфортное дневное окно (например, с 09:00 до 21:00 по местному времени получателя).
Согласие, кнопка отписки и защита репутации бота
Telegram отслеживает жалобы пользователей. Если заметная часть получателей нажимает кнопку «Пожаловаться на спам» или останавливает бота сразу после сообщения, платформа может ограничить рассылку или навсегда заблокировать токен бота. Инженерная защита строится на двух правилах: добровольное согласие и прозрачная отписка.
Пользователь должен давать осознанное согласие на получение сообщений при первом запуске бота или в меню настроек. Важно разделять сервисные сообщения (коды авторизации, статусы заказов) и маркетинговые уведомления (акции, новости). Сервисные уведомления отправляются всегда, а рекламные рассылки требуют отдельного разрешения.
В каждое маркетинговое сообщение рекомендуется встраивать инлайн-кнопку «Отписаться». Нажатие кнопки обрабатывается через callback_query и моментально переводит статус подписки в базе данных в неактивное состояние. Пользователь, у которого есть возможность отписаться в один клик, не станет блокировать бота целиком и не нажмет кнопку жалобы.
- Разделение типов сообщений: сервисные уведомления отделены от рекламных кампаний на уровне таблиц и очередей.
- Инлайн-кнопка отписки: возможность прекратить получение рассылок прямо под текстом сообщения без блокировки бота.
- Отслеживание процента блокировок: рост доли блокировок после рассылки служит сигналом к пересмотру частоты и содержания рассылок.
- Запрет навязывания: исключение пользователей из маркетинговых выборок при первом же запросе на отписку.
Отчеты о доставке и когда готовые решения выгоднее
Надежная рассылка в телеграм боте завершается формированием детального отчета. Администраторы и маркетологи должны видеть объективную статистику: сколько сообщений доставлено успешно, сколько пользователей заблокировали бота, сколько попыток завершилось сетевыми ошибками и какова реальная скорость отправки. Эти данные позволяют вовремя чистить базу подписчиков и планировать новые кампании.
Собственный сервис рассылки на Go необходим проектам с большой базой, динамической персонализацией сообщений, интеграцией с CRM и требованиями к безопасности данных. Разработку таких специализированных систем выполняет студия Anaxita — подробности смотрите в разделе разработку телеграм-ботов. Если бот рассылает персонализированные чеки, напоминания о записях или закрытый контент, готовые платформы не дадут нужного контроля.
Однако для многих типовых задач писать отдельный бэкенд не требуется. Если цель — публикация общих новостей для широкой аудитории без персонализации, оптимально использовать публичный Telegram-канал. В каналах доставка выполняется инфраструктурой Telegram без ограничений Bot API. А для проверки первых гипотез с небольшой базой часто проще использовать no-code конструкторы, о чем мы рассказывали в статье n8n или свой код.
- Telegram-канал: идеален для общих новостей и анонсов; нет лимитов Bot API, нулевая нагрузка на ваш сервер.
- No-code сервисы: подходят для небольших баз и простых триггеров на этапе тестирования бизнес-идеи.
- Собственный бэкенд на Go: незаменим для баз от десятков тысяч контактов, персональных данных, CRM-интеграций и жестких требований к отказоустойчивости.