Часть 1. Введение: когда «просто отправить сообщение» превращается в инженерную задачу
Это первая часть цикла статей о разработке системы публикации структурированных интерактивных постов через Telegram Bot API. В следующих частях — архитектура, рендеринг шаблонов и управление доступом к закрытым чатам.
С чего всё начинается
Представьте типичную задачу: пользователь вашего сервиса хочет опубликовать в своём Telegram-канале структурированный пост. Не просто текст — а пост с заголовком, многострочным описанием, блоком реквизитов, динамическим индикатором прогресса и интерактивными кнопками. Пост, который после публикации будет обновляться в реальном времени по мере поступления новых данных. Пост, под которым есть кнопка, открывающая отдельный диалог в боте — и всё это происходит без перехода в браузер, без форм, без лишних шагов.
На первый взгляд — ничего сложного. Telegram Bot API умеет отправлять текст, прикреплять медиа, рисовать inline-кнопки. Но именно в этот момент начинается то, что разработчики называют «дьявол в деталях».
На практике задача немедленно разбивается на несколько инженерных проблем, каждая из которых требует отдельного решения. И если пропустить хотя бы одну — система либо ломается при первом же граничном случае, либо создаёт такой UX, что пользователи просто не понимают, что происходит.
Проблема первая: лимиты Telegram API — жёсткие и молчаливые
Telegram накладывает ограничения, которые не всегда очевидны из документации, но дают о себе знать в продакшене.
Максимальная длина одного сообщения — 4096 символов для текстовых сообщений и 1024 символа для подписи к медиафайлу (caption). Звучит как много — до тех пор, пока пост не начинает формироваться динамически из нескольких источников данных одновременно.
Рассмотрим конкретный пример. Пост включает: заголовок (до 255 символов), описание (до 400 символов), блок динамических данных с несколькими строками (каждая строка — название поля плюс значение), блок реквизитов (несколько записей, каждая из которых может занимать до 60–80 символов с учётом иконки, типа и значения), строку прогресса («Собрано: X из Y — Z%»), строку дедлайна и призыв к действию.
Теперь добавьте к каждому полю управляющие символы разметки: звёздочки для жирного текста, обратные кавычки для моноширинного блока (именно в них удобно размещать копируемые значения — Telegram автоматически добавляет кнопку копирования по нажатию), символы переноса строки между блоками. Всё это стремительно съедает лимит.
Если пост содержит медиа (фото или видео), лимит на подпись сокращается с 4096 до 1024 символов — и значительная часть контента просто не помещается. Система должна уметь принимать это решение заблаговременно: ещё на этапе preview, до публикации, вычислять итоговую длину с учётом всех управляющих символов и, если лимит превышен, предлагать пользователю сократить конкретные поля — с указанием, какое именно и насколько.
Это не единственный лимит. Telegram ограничивает количество запросов к API: не более 30 сообщений в секунду в одном чате и не более 20 сообщений в секунду глобально для одного бота. При массовой рассылке уведомлений подписчикам — когда система должна отправить персональное сообщение каждому из N пользователей — это ограничение становится реальным инженерным вызовом. Необходима очередь с контролем частоты и graceful retry при получении ошибки 429 Too Many Requests.
Проблема вторая: MarkdownV2 — формат, который легко сломать
Telegram поддерживает три режима форматирования текста: обычный (без разметки), HTML и MarkdownV2. На практике MarkdownV2 даёт наиболее читаемый результат в большинстве клиентов — жирный текст, курсив, моноширинные блоки, ссылки выглядят именно так, как ожидает пользователь.
Но у MarkdownV2 есть критическое свойство: он требует экранирования большинства специальных символов во всём тексте сообщения, включая те, которые в тексте используются как обычные знаки препинания. Полный список символов, требующих экранирования (добавление символа \ перед ними): _, *, [, ], (, ), ~, ` `, >, #, +, -, =, |, {, }, ., !`.
Теперь рассмотрим, что происходит с данными, которые вводит пользователь. Название организации — «А.В. Иванов & Ко», описание — «Помощь детям (Москва). Цель: 50.000 ₽!», реквизит — email user@example.com. Любой из этих текстов, вставленный в MarkdownV2-шаблон без предварительной обработки, немедленно вызывает ошибку Telegram API: Bad Request: can't parse entities: Character '.' is reserved and must be escaped with the preceding '\' .
Telegram не уточняет, в какой позиции строки находится проблемный символ. Он возвращает общую ошибку разбора. При динамически формируемом тексте, где десятки полей собираются в единую строку, отладка такой ошибки без превентивной обработки превращается в поиск иголки в стоге сена.
Решение — функция экранирования, которая должна применяться к каждому динамическому фрагменту текста перед его вставкой в шаблон. Принципиально важна граница её применения: экранировать нужно только пользовательский контент и переменные данные, но не управляющие символы самого шаблона — звёздочки для жирного текста, обратные кавычки для моноширинных блоков. Если экранировать шаблон целиком, разметка перестаёт работать. Если не экранировать данные — API возвращает ошибку.
Отдельный случай — URL в ссылках. В MarkdownV2 ссылка записывается как [текст ссылки](URL). В части URL правила экранирования отличаются от правил для основного текста: здесь экранируются только символы \ и ). Если применить к URL ту же функцию экранирования, что и к обычному тексту, ссылка перестаёт быть валидной. Следовательно, система должна разделять обработку «текстовых» и «URL»-фрагментов шаблона.
Это делает тривиальную на вид задачу — «вставить данные в шаблон» — полноценной системой рендеринга с типизированными слотами и отдельными правилами преобразования для каждого типа данных.
Проблема третья: состояние кнопок и синхронизация интерфейса
Telegram inline-кнопки под сообщением — это не просто визуальные элементы. Каждая кнопка содержит callback_data — строку, которая отправляется боту при нажатии. Бот должен идентифицировать, к какому именно объекту относится это нажатие, какое действие выполнить и как обновить интерфейс после выполнения.
Вот где начинаются сложности.
Идентификация контекста. Один и тот же пост может быть опубликован в разных каналах. Один и тот же пользователь может нажать кнопку «Поддержать» сразу в нескольких постах. callback_data ограничена 64 байтами — в неё нужно уместить идентификатор объекта, тип действия и достаточно информации для однозначной обработки запроса. При проектировании структуры callback_data компактность и читаемость вступают в противоречие, и разработчику приходится выбирать схему кодирования (например, action:entity_type:entity_id), которая укладывается в лимит.
Двойные клики. Пользователь нажал кнопку. Бот начал обрабатывать запрос — обратился к базе данных, сделал несколько API-вызовов. Это занимает 300–800 миллисекунд. За это время нетерпеливый пользователь нажал кнопку ещё раз. Бот получил два одинаковых callback_query и начал выполнять действие дважды.
Telegram предоставляет метод answerCallbackQuery, который убирает индикатор загрузки с кнопки. Вызов этого метода до завершения основной логики — не лучшая практика: пользователь видит, что кнопка «отреагировала», и может нажать снова. Вызов после завершения — создаёт окно для дублирования. Корректное решение требует идемпотентной обработки: система должна идентифицировать повторный запрос по уникальному callback_query_id или по состоянию самой сущности и возвращать предыдущий результат без повторного выполнения действия.
Редактирование сообщения. После выполнения действия по нажатию кнопки — например, подтверждения транзакции — логично обновить само сообщение: изменить текст, обновить прогресс-ба��, изменить набор кнопок. Telegram предоставляет метод editMessageText. Но у него есть ограничение: если сообщение было опубликовано больше 48 часов назад или если текст нового сообщения идентичен предыдущему — редактирование завершится ошибкой Bad Request: message is not modified. Система должна обрабатывать этот сценарий явно, а не допускать, чтобы ошибка 48-часового давности роняла обработчик callback.
Проблема четвёртая: мастер создания поста в условиях stateless-протокола
Telegram-бот по своей природе работает в stateless-среде: каждое входящее сообщение от пользователя — это независимый HTTP-запрос. Между запросами бот «не помнит» ничего о предыдущем состоянии диалога.
Создание структурированного поста требует последовательного сбора множества данных: название, описание, медиафайл, числовые параметры, дата, блок реквизитов (который сам по себе является подпроцессом с несколькими итерациями). Пользователь проходит девять последовательных шагов, на каждом вводя очередную порцию информации.
Для реализации такого многошагового диалога необходим механизм хранения промежуточного состояния. Простое решение — in-memory хранение в оперативной памяти процесса — работает ровно до первого рестарта сервера. При масштабировании на несколько инстансов бота (или при использовании serverless-деплоя) сессия, сохранённая в памяти одного инстанса, недоступна другому.
Правильно спроектированная система сессий должна быть внешней по отношению к процессу бота — либо Redis, либо база данных. При этом возникают новые вопросы: как долго хранить незавершённые сессии? Что делать, если пользователь начал создание поста, закрыл Telegram и вернулся через три часа — его черновик должен сохраниться? Как обрабатывать случай, когда пользователь нажимает кнопку «Назад» на третьем шаге мастера, а не просто пишет новое сообщение?
В описываемой системе реализован паттерн «защиты черновика»: незавершённый пост сохраняется на каждом шаге, пользователь может прервать процесс и вернуться к нему позже. На финальном экране — сводка всех введённых данных с возможностью отредактировать любое поле без возврата к началу. Только после явного подтверждения система выполняет публикацию.
Проблема пятая: автоматическое управление доступом к закрытым чатам
Отдельный инженерный вызов — интеграция с группами обсуждений Telegram-каналов.
Многие каналы имеют привязанную группу обсуждений: закрытый чат, где подписчики могут общаться. Задача системы — автоматически предоставлять доступ в такой чат определённым пользователям после наступления заданного события (например, подтверждения транзакции).
Telegram Bot API позволяет генерировать пригласительные ссылки с ограниченным сроком действия через метод createChatInviteLink. Казалось бы — всё просто: событие наступило, сгенерировали ссылку, отправили пользователю.
Но реальность сложнее. Во-первых, бот должен быть администратором группы с правами на создание пригласительных ссылок — это требование, которое нужно проверять заблаговременно при привязке канала, а не в момент, когда пользователь уже ждёт ссылку. Во-вторых, если пользователь уже состоит в группе (например, вступил ранее), генерация новой ссылки бессмысленна — нужно вместо этого снять возможные ограничения через restrictChatMember. В-третьих, ошибки Telegram API при работе с чатами крайне разнообразны: бот может потерять права администратора, группа может быть удалена, пользователь может заблокировать бота — каждый из этих сценариев требует отдельной обработки и уведомления ответственного лица.
Система должна не просто «попробовать выдать доступ» — она должна верифицировать права перед выполнением действия, детектировать ошибки, классифицировать их как временные (сеть, rate limit) или постоянные (нет прав), и в случае постоянной ошибки немедленно уведомлять оператора с описанием проблемы и инструкцией по её устранению.
Почему всё это важно
Каждая из описанных проблем решаема в изоляции. Когда они встречаются одновременно в одной системе, возникает то, что можно назвать «комбинаторной сложностью мессенджерных интерфейсов». Ошибка в одном слое (неправильное экранирование) ломает другой слой (API возвращает ошибку, не доходя до логики управления кнопками). Ошибка в управлении сессией ломает третий слой (пользователь видит результат чужого действия). Отсутствие rate limiting делает всю систему нестабильной под нагрузкой.
Проектирование такой системы требует одновременного учёта ограничений протокола, требований UX и архитектурных решений о хранении состояния. Нельзя начать с «быстрого прототипа» и «потом починить» — базовые архитектурные решения, принятые на старте, определяют, насколько система окажется хрупкой при первом нетривиальном сценарии использования.
В следующих частях этого цикла — разбор архитектуры системы, реализация рендерера шаблонов с корректным экранированием, механика диалогового мастера и схема управления доступом к закрытым чатам.
Живой пример того, как описанные механизмы работают в production — в [Telegram-канале проекта](https://t.me/qrperevod). Там публикуются реальные посты, сформированные системой, логи разработки и анонсы новых возможностей.
