HTML-виджеты в сообщении бота Telegram: что влезает в 4 КБ

Что вышло и откуда я это взял

Пост про widget-sandbox в канале Open Source вышел 7 ноября. Пересказом поста я ограничиваться не хотел и открыл три первоисточника: репозиторий TelegramMessenger/widget-sandbox, страницу core.telegram.org/bots/widgets и журнал изменений Bot API. Репозиторий я склонировал и прочитал документацию. На 10.11.2026 последний тег v0.6.3, коммит от 9 ноября. В скачанной истории пять авторов, и один из них написал основную часть коммитов.

Файла LICENSE в корне репозитория я не нашёл. Есть только список сторонних компонентов, у них MIT и ISC. Для бота это неважно: вы шлёте HTML, а движок крутится у Telegram. Если же кто-то захочет встроить песочницу в собственный клиент, условия придётся уточнять.

В README есть фраза, что виджет не может писать боту. Руководство для авторов и справочник Bot API говорят обратное: виджет посылает боту короткий запрос, как нажатие callback-кнопки. Я верю справочнику Telegram, а README считаю устаревшим.

Что можно сделать виджетом

Виджет это один HTML-документ с инлайновыми CSS и JavaScript, до 32 КБ исходника и до 4096 байт после сжатия zlib. Скрипт запускается в движке QuickJS на телефоне. Рисует Telegram сам, поэтому вид одинаков на iOS, Android и десктопе, а цвета берутся из темы чата. Можно кнопки, canvas, SVG, анимации и подстройку под тему чата.

Связь с ботом одна: запрос от 1 до 64 байт, ответ бота до 1024 байт. Состояние виджета бот хранит в двух полях по 1024 байта и меняет методом editMessageWidgetData. Виджет читает состояние и перерисовывается. Сам он состояние изменить не может.

Из этого получаются четыре сценария для магазина, записи или сервиса.

Статус заказа. Бот шлёт виджет с четырьмя этапами, а потом только меняет состояние: принят, собираем, у курьера, доставлен. Новое сообщение на каждый этап не нужно. Свой пример на 782 байта я прогнал через песочницу из репозитория: проверка размера и валидатор прошли без замечаний.

Выбор времени. Шесть кнопок со слотами, занятые серые. Тап уходит боту запросом вида slot:14:30, бот отвечает текстом и меняет состояние. Мой пример занимает 1064 байта. Про запись на услуги в мессенджере я писал отдельно в статье про бота для записи.

Калькулятор стоимости. Кнопки плюс и минус, пересчёт на телефоне, боту ничего не уходит. Одну такую заготовку я отрисовал в Telegram Desktop 7.4.0. Версия 7.3.5 показала заглушку.

Мини-опрос. Общее состояние на 1024 байта вмещает счётчики для нескольких вариантов. Бот обновляет его один раз в секунду, а виджет рисует полоски.

Чего виджет не умеет

Сеть закрыта полностью. fetch, XMLHttpRequest и WebSocket выбрасывают ошибку, внешние скрипты, шрифты и картинки не грузятся. Картинки возможны только как data: и встроенный SVG.

Ввода нет. Полей, селектов и клавиатуры в виджете не бывает, остаются тапы и горизонтальные жесты. Имя, телефон и адрес по-прежнему надо спрашивать обычными сообщениями. Видео и аудио нет, внутри виджета ничего не прокручивается, высота от 50 до 600 пикселей.

Код отправленного виджета изменить нельзя. Новый макет это новое сообщение. Лимиты тоже жёсткие: 8 МБ памяти и около 300 миллисекунд процессорного времени в секунду. В README указано 64 МБ, но я ориентируюсь на цифру из руководства, она меньше. Запросов можно слать не больше 5 за 5 секунд от одного пользователя на все виджеты бота.

Состояние и код надо считать публичными, секреты туда не кладут. Доступность пока слабая: атрибуты aria сохраняются, но ничего не делают, поэтому главное дублируйте в подписи.

Где виджет работает сегодня

Здесь легко ошибиться, потому что в репозитории описан полный набор, а в продакшене включена часть. По журналу Bot API 10.4 бот может отправить виджет только в личный чат. Отправленный виджет автоматически получает защиту от пересылки. Группы, режим inline и пересылка работают на тестовом сервере Telegram, там можно проверить всё. В каналы бот виджеты не отправляет. Переслать их туда пользователи могут только на тестовом сервере.

В документации Telegram минимальная версия приложения не названа. Одно российское издание пишет, что виджеты заработали в стабильной версии 13.2, и это единственный источник, который я нашёл. Я не проверял виджет на живом iPhone и Android, только в Telegram Desktop. На старом клиенте сообщение превращается в неподдерживаемое медиа с подписью. Если подписи нет, человек увидит пустую заглушку.

Что можно сделать уже сейчас

Я бы начал с одного экрана, где бот отвечает длинным текстом или цепочкой из пяти кнопок. Подойдёт статус заказа, подбор слота или расчёт. Остальные экраны остаются как есть, бот целиком переписывать не нужно.

Первым шагом отправляю виджет на тестовом сервере и смотрю его в тёмной и светлой теме. Вторым шагом проверяю размер так, как считает сервер: сжатие zlib на уровне 9. Запас оставляю до 3800 байт, потому что сервер отказывает с ошибкой INPUT_MEDIA_WIDGET_TOO_LARGE. Третьим шагом пишу подпись с готовым итогом, например «Заказ 1042: собираем, обновлено в 14:20». Четвёртым оставляю под виджетом обычные inline-кнопки, чтобы любой клиент мог нажать то же самое.

POST /bot<token>/sendWidget
{ "chat_id": 111, "html": "...", "allow_queries": true,
  "caption": "Заказ 1042: собираем" }

Когда нужен ввод, большие данные или карта, берите Mini App. Хранилище состояния для ботов и мини-приложений удобно держать в PocketBase. Как выбирать между Telegram, MAX и VK, я разбирал в отдельной статье.

Частые вопросы

Виджет заменит Mini App?

Нет. Mini App открывается отдельным окном, ходит в сеть и принимает ввод. Виджет живёт внутри сообщения и сети не имеет. Для короткого статуса или выбора он удобнее, для оформления заказа с адресом нужен Mini App.

Что увидит клиент со старой версией Telegram?

Неподдерживаемое медиа с вашей подписью. Поэтому подпись должна содержать главный итог, а кнопки под виджетом дают запасной путь.

Можно ли отправить виджет в группу или канал?

В продакшене на 10.11.2026 нельзя ни то ни другое. Группы доступны на тестовом сервере, каналы закрыты полностью. Условия меняются, поэтому я проверяю справочник перед каждым внедрением.

Коротко о главном

Виджеты закрывают маленькие сценарии: статус, слот, расчёт, голосование. Они появились 9 ноября, работают пока в личном чате, и всё, что нужно человеку, должно дублироваться в подписи и кнопках. Что-то из этого я проверял в песочнице и на Desktop, живой телефон не тестировал.

Хотите, чтобы бот показывал статусы и выбор времени одним аккуратным блоком, а не десятью сообщениями? Напишите мне в Telegram слово «ПУЗЫРЬ». Посмотрим, какой экран вашего Telegram-бота стоит перевести на виджет и что оставить на кнопках.