Как работают виджеты в сообщениях Telegram на Android, iOS и macOS

Виджеты в сообщениях Telegram — это мини-программы из HTML, CSS и JavaScript, которые живут прямо в пузыре переписки: игра, калькулятор, опрос или ответ бота открываются без отдельного окна и без Mini App. В клиентах Telegram их называют по-разному — message widgets, HTML bubbles (модуль HTMLBubbles в бете для macOS), блок tgwidget в rich-сообщении, — но речь об одном механизме. Он уже работает в бетах Telegram для Android, iOS и macOS, а лист ожидания конструктора виджетов без кода открыт в @catalogue_app.

Встать в лист ожидания виджетов

Что такое виджет в сообщении

Обычное сообщение показывает текст и медиа. Виджет — это отдельный тип медиа, messageMediaWidget: внутри лежит сжатый HTML-документ со своими стилями и скриптами, его размеры и два набора данных. Клиент рисует документ в пузыре и исполняет его JavaScript в песочнице, а сам виджет реагирует на нажатия, анимируется, хранит состояние и отвечает теме чата.

Где виджеты уже работают

Бета Android раздаётся каналом бета-тестеров и прямой ссылкой с сайта Telegram. Протокол клиента в ней — слой 233, на один новее публичного: под виджет в нём уже есть типы для доставки сервером, для инлайн-ответов ботов и для обновления данных после отправки.

Как виджет работает на Android

Браузера под виджетом нет. Разметку раскладывает и рисует нативный рендерер на основе litehtml, а JavaScript исполняет отдельный интерпретатор QuickJS в своём потоке. DOM для скрипта эмулирован: изменения уходят в рендерер пачками, и каждую пачку перед отрисовкой проверяет валидатор. Настоящее ли нажатие, решает нативный судья касаний, а не скрипт, — поэтому синтетический клик не выдаёт себя за палец пользователя.

Подробный разбор сборки — в материале о бетах Android и iOS.

Как виджет работает на iOS и macOS

На Apple-платформах документ рисует WebKit в отдельном модуле WidgetSandbox, закрытом от сети тремя слоями: политикой безопасности контента, списком правил, который блокирует http, https и ws, и удалением сетевых классов из окна до запуска кода. В бете для macOS вместе с модулем HTMLBubbles лежит библиотека three.js, которую сообщение подключает внутренней ссылкой app:three: 3D-сцены рисует Metal-рендерер приложения. Как это выглядело в первых сборках — в материале о бете для macOS.

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

• Вёрстка и анимация — flex, градиенты, скругления, transform, CSS-анимации и transitions.
• Графика — SVG и canvas 2D: пути, градиенты, паттерны, работа с пикселями.
• Формы — текстовые поля, списки, ползунки, кнопки, раскрывающиеся блоки.
• Состояние — localStorage у каждого виджета свой и хранится вместе с сообщением: счёт игры и введённые данные переживают перезапуск клиента.
• Тема — цвета чата приходят CSS-переменными --tg-theme-*, и виджет сам перекрашивается в светлую и тёмную тему.
• Отклик — вибрация через HapticFeedback, ссылки по нажатию, копирование текста.
• Бот — по нажатию виджет отправляет своему боту до 64 байт и получает ответ до 1 024 байт; бот может обновить данные уже отправленного виджета.
• Зритель — виджет знает, кто его открыл (id, имя, Premium) и в каком чате лежит.

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

Сети у виджета нет совсем: fetch, XMLHttpRequest, WebSocket и воркеры заменены заглушками. Это свойство, а не недоработка: полученный виджет не может выдать IP читателя и работает без интернета. Живые данные приходят через бота — запросом по нажатию или обновлением данных сообщения.

Квота на одну задачу JavaScript — 500 мс процессора, памяти — 64 МБ. Высота пузыря — от 50 до 600 dp на Android и от 24 до 900 pt на iOS. Анимации за экраном ставятся на паузу.

Как уложиться в квоту

Тяжёлая работа дробится на куски меньше 500 мс через requestAnimationFrame или setTimeout. Игровой цикл с фиксированным шагом физики помещается в квоту с запасом: раннер в духе Geometry Dash проходит весь уровень в 3 289 кадров за 30 мс процессора, до 109 команд canvas на кадр.

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

• Игры — аркады на canvas, головоломки, кликеры, текстовые квесты, турниры на счёт прямо в чате.
• ИИ-виджеты — вопрос нажатием, ответ модели через бота в тот же пузырь.
• Калькуляторы и конвертеры — валюты, проценты, единицы, сплит счёта на компанию.
• Опросы и квизы — со своим оформлением, счётом и результатом на месте.
• Карточки и графики — профиль, прогноз, статистика, нарисованные по данным сообщения.
• Intelligent UI — интерфейс, который бот собирает под конкретный запрос: форма бронирования, выбор времени, корзина.

И не только: виджет — это HTML-документ, и всё, что помещается в песочницу, можно отправить сообщением.

🎮 Игры в сообщениях — в лист ожидания

🤖 ИИ-виджеты — в лист ожидания

🧮 Калькуляторы и конвертеры — в лист ожидания

Свой виджет без кода

Виджет — это одно сообщение с документом внутри, поэтому его можно собрать из готовых блоков, без программирования. Конструктор виджетов без кода готовит @catalogue_app: шаблон игры, квиза или калькулятора, свои тексты и цвета — и готовый виджет уходит в любой чат. Свой экземпляр можно отправить из собственного бота, созданного в том же @catalogue_app, и поделиться шаблоном, чтобы другие сделали из него форк.

Лист ожидания собирает тех, кто хочет свой виджет: когда виджеты выйдут во всех приложениях Telegram, @catalogue_app напишет им первым.

🧩 Свой виджет без кода — в лист ожидания

Игра-виджет, которая уже работает в Android-бете Telegram, отправляется командой /game в @catalogue_app.

🎮 Попробовать игру-виджет

Вопросы

Что такое HTML bubbles в Telegram?

Так называется модуль виджетов в бете Telegram для macOS: сообщение, свёрстанное на HTML и CSS со встроенным JavaScript, живёт прямо в пузыре чата. В Android и iOS тот же механизм называется виджетами в сообщениях.

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

Виджеты рисуются в бетах Android, iOS и macOS. Метода отправки в Bot API пока нет; в протоколе беты уже есть типы для доставки виджета сервером и инлайн-ответом бота.

Чем виджет отличается от Mini App?

Mini App открывается отдельным окном и грузит страницу с сервера, виджет живёт в ленте и несёт весь код в самом сообщении. Сети у виджета нет, связь с внешним миром идёт через бота.

Нужно ли уметь программировать?

Чтобы написать виджет с нуля — да, это HTML, CSS и JavaScript. Чтобы собрать свой из шаблона — нет: для этого и готовится конструктор без кода в @catalogue_app.

Когда виджеты выйдут в стабильных версиях?

Telegram дату не называл. Механизм уже в бетах всех трёх платформ, и в бете Android под него есть серверные типы протокола.