В тестовой документации Telegram Bot API 10.4 появились методы для отправки интерактивных HTML-виджетов прямо в переписку. Боты смогут показывать голосования, счётчики и небольшие игровые интерфейсы внутри сообщения, принимать нажатия и обновлять данные без повторной отправки карточки. Пока описанные возможности относятся к тестовой реализации: в официальном списке стабильных релизов последней значится версия Bot API 10.3.
Виджет Telegram работает непосредственно внутри сообщения
5 ноября 2026 года стало известно о публикации тестовой документации Bot API 10.4 для отправки виджетов. На неё указал Telegram-канал teleLakel, сославшись на раздел The Bot API (10.4) в открытом репозитории TelegramMessenger/widget-sandbox на GitHub. В самой спецификации описаны команды для ботов, модель обмена данными и ограничения экспериментальной реализации.
Виджет представляет собой компактную страницу на HTML, CSS и JavaScript, которая отображается внутри сообщения Telegram. Пользователь видит готовый интерфейс прямо в переписке: например, кнопки голосования с результатами, панель со счётом или небольшую игру. Размер блока ограничен, поэтому для сложных экранов такой формат не предназначен.
Сейчас похожие задачи боты решают с помощью текста и inline-кнопок либо Telegram Mini Apps. У мини-приложения есть отдельная веб-страница, а виджет живёт внутри самого сообщения. Для голосования это меняет сценарий: человек может нажать элемент карточки и увидеть обновлённые данные, оставаясь в чате. В сравнении с Rich Messages, которые Telegram развивал в Bot API 10.1–10.3 для структурированного контента, виджет дополнительно исполняет ограниченный JavaScript-код и реагирует на действия пользователя.
Новые методы Bot API 10.4 для отправки и обновления виджетов
Документация перечисляет несколько методов, которые составляют основу взаимодействия бота с новым форматом. Они разделяют создание интерфейса, повторное использование общей карточки и обработку событий от читателя.
| Метод или событие | Назначение |
sendWidget | Отправляет новый виджет с HTML-кодом и исходными данными |
sendSharedWidget | Отправляет уже созданный общий виджет по его widget_id |
answerWidgetQuery | Отвечает на запрос пользователя из виджета |
editMessageWidgetData | Меняет данные виджета в конкретном сообщении, в том числе в inline-сообщении |
editSharedWidgetData | Обновляет общие данные виджета по widget_id |
widget_query | Уведомляет бота о действии в исходном сообщении |
shared_widget_query | Передаёт запрос из пересланной копии общего виджета |
Для inline-режима, когда пользователь вызывает бота в чужом чате через @имя_бота, предусмотрены объекты InputWidgetMessageContent и InputSharedWidgetMessageContent. Так виджет можно предложить как результат поиска бота и вставить в переписку.
Один из практических сценариев — интерактивный опрос. Бот создаёт карточку с вариантами ответа, пользователь нажимает кнопку, после чего Telegram передаёт боту widget_query. Бот обрабатывает событие, отвечает через answerWidgetQuery и при необходимости обновляет результаты. Схема напоминает работу callback-кнопок, но позволяет нарисовать более насыщенный интерфейс.
Для запросов установлены отдельные пределы: полезная нагрузка действия — от 1 до 64 байт, не более пяти запросов за пять секунд от одного пользователя к боту. Сервер ожидает ответ до 15 секунд. Превышение лимита или задержка приводят к ошибкам, описанным в спецификации.
Общие виджеты синхронизируют данные между сообщениями
Главное отличие новой модели — возможность создать общий виджет (is_shared), который получает идентификатор widget_id. Один и тот же объект можно разместить в нескольких сообщениях, а бот сможет изменить его общее состояние через editSharedWidgetData.
В документации выделены два вида данных:
public_data— общие данные, например число голосов, текущий счёт или опубликованный результат. В общем виджете их обновление относится ко всем сообщениям, связанным с однимwidget_id.chat_data— состояние конкретного исходного сообщения, например текущий ход игры в определённом чате. При пересылке оно не переносится.
Для обоих полей предусмотрено ограничение в 1024 байта. Код HTML после отправки остаётся неизменным: бот управляет состоянием, а для принципиально другого интерфейса создаёт новую карточку.
Что это даёт на примере? Организатор запускает опрос и делится виджетом в нескольких группах. При использовании общего виджета все экземпляры могут отображать один счёт голосов. Обычная статическая карточка при пересылке сохраняет копию публичных данных на момент отправки и дальше не синхронизирует её с оригиналом.
Общие данные загружаются по запросам клиента Telegram. По умолчанию в спецификации указан интервал проверки 30 секунд, который может меняться в диапазоне от 5 до 3600 секунд. Поэтому обновление на сервере и момент появления нового значения на экране у разных читателей не обязательно совпадают.
Пересылка, группы и каналы имеют разные правила
Прямая отправка виджета предусмотрена в личный диалог с ботом, обычную группу и супергруппу, где бот состоит и имеет право отправлять медиа. В тестовой спецификации каналы пока исключены из прямой отправки. При этом переслать сообщение с виджетом можно и в канал: правила пересылки отличаются от правил создания нового сообщения.
У пересланного виджета отмечается признак is_copy. Возможность обращаться к боту зависит от разрешений исходного общего объекта. В описании Bot API 10.4 для такого сценария используется сочетание is_shared и allow_queries; отдельного параметра fwd_allow_queries на уровне Bot API в таблице нет.
Из пересланной копии бот получает запрос shared_widget_query с идентификатором объекта, отправителем действия и данными запроса. Сведения о чате пересылки при этом не передаются. Это позволяет проводить взаимодействия с карточкой, не раскрывая боту расположение каждой её копии.
Ограничения HTML-виджетов и защита пользователей
Разработчики WidgetSandbox ограничили исполняемый код и способы отображения содержимого. В документации обозначены конкретные рамки:
| Параметр | Ограничение |
| Исходный HTML вместе со встроенными стилями и скриптами | До 32 768 байт |
| Объём после сжатия zlib | До 4096 байт |
| Ширина области отображения | Примерно 200–600 пикселей с учётом экрана |
| Высота | До 600 пикселей |
| Прямая сеть из JavaScript | Запрещена |
| Внешние скрипты и ресурсы | Запрещены |
| Поля ввода, видеоплееры и прокрутка внутри карточки | Не поддерживаются профилем виджетов |
JavaScript работает в изолированной среде QuickJS. Запросы через fetch, XMLHttpRequest и WebSocket недоступны. Изображения могут храниться внутри документа в виде data:-данных, а клиент проверяет элементы, атрибуты и CSS по разрешённому набору. Для общения с сервером бота предусмотрен контролируемый механизм запросов через Telegram.
Такая архитектура влияет на функции будущих карточек. Кнопки, простые анимации, диаграммы и мини-игры укладываются в идею виджета; форма с произвольным вводом текста или интерфейс, который самостоятельно загружает информацию из внешнего API, требует другой реализации. Хранение локального состояния внутри сообщения позволяет, например, запоминать игровой прогресс на устройстве, но оно отдельно от данных, которые сохраняет бот.
Почему тестовая документация пока не равна публичному релизу
В разделе Bot API 10.4 указано, что совместимость проверяли на бета-сервере 28 октября 2026 года. Именно по результатам этих испытаний перечислены ограничения, обнаруженные в действующей тестовой реализации.
Например, на момент проверки сервер отклонял copyMessage для виджетов, хотя в общей спецификации описано предполагаемое поведение при копировании. Поле can_send_background_queries также не включалось даже в личном чате с ботом. Указанные расхождения показывают, почему возможности тестового API нельзя автоматически считать окончательными.
Есть ограничение и по совместимости клиентов. Для интерактивных карточек используется Telegram API layer 233. Старые версии приложения получают сообщение как неподдерживаемое медиа и могут показать текст подписи и стандартную заглушку. Поэтому доступность интерфейса зависит одновременно от серверной реализации и версии самого клиента Telegram.
В официальной истории релизов Bot API по состоянию на 6 ноября 2026 года последней опубликована версия 10.3 от 24 августа 2026 года. Отдельного объявления о стабильном выпуске Bot API 10.4 в этом списке пока нет. Новая документация описывает направление разработки и позволяет разбирать будущий формат уже сейчас, но сроки общего доступа и окончательный набор параметров пока не закреплены публичным стабильным changelog.
