Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram — это небольшие интерактивные HTML-блоки, которые бот отправляет внутри сообщения методом sendWidget. Они появились в Bot API 10.4 9 ноября 2026 года. Виджет — один HTML-документ размером до 32 КБ: приложение Telegram выполняет его на устройстве пользователя без доступа к сети и рисует в стиле чата. Это может быть карточка заказа с обновляемым статусом, счётчик, опрос с живыми полосками результатов или промокод, который копируется одним нажатием.
Где виджеты работают сейчас: в продакшене бот может отправлять виджеты только в личный чат с пользователем, причём такие сообщения отправляются с защищённым содержимым, поэтому переслать их нельзя. Виджеты в группах, в инлайн-режиме и в пересылках пока работают только на тестовом сервере.
Что такое виджет Telegram
- Один HTML-документ. Стили и скрипты — только встроенные (
<style>и<script>), картинки — только какdata:-URL или inline SVG. Не больше 32768 байт в UTF-8 и не больше 4096 байт после сжатия zlib уровня 9. Обёртка<html>и<body>не обязательна — достаточно фрагмента. - Песочница. JavaScript выполняется в QuickJS — компактном JS-движке, а не в WebView. Приложение проверяет каждое изменение, которое делает виджет, на соответствие профилю виджета и рисует только то, что прошло проверку. Поэтому виджет выглядит одинаково на iOS, Android, macOS, в Telegram Desktop и в веб-версии.
- Без сети.
fetch,XMLHttpRequest,WebSocketи другие сетевые API выбрасываютNetworkDisabledError. Внешние скрипты, стили, шрифты и картинки никогда не загружаются, встроенных библиотек тоже нет. - Нативный вид. Палитра чата доступна в CSS-переменных
--tg-theme-*, а<button>без стилей рисуется как родная кнопка приложения. - Без клавиатуры. Поля ввода, выпадающие списки и textarea удаляются. Виджет реагирует на нажатия, pointer-события, горизонтальные перетаскивания и долгие нажатия.
Код и состояние: chat_data и public_data
Виджет — это неизменяемый код плюс изменяемое состояние. HTML задаётся при отправке и больше не меняется: метода, который бы его заменил, нет. Меняется только состояние, и пишет его исключительно бот. Виджет читает его из TelegramWidget.chatData и TelegramWidget.publicData и перерисовывается по событиям chatDataChanged и publicDataChanged.
| Параметр | Состояние чата (chat_data) | Общее состояние (public_data) |
|---|---|---|
| К чему привязано | К одному исходному сообщению | К сообщению статичного виджета или к общему виджету везде, где он показан |
| Кто видит | Только в этом чате (в группе — одно на всех участников) | Везде, где показан виджет |
| В пересылке | Никогда | Копия (статичный виджет) или живое общее состояние (общий виджет) |
| Размер | До 1024 байт текста | До 1024 байт текста |
| Чем меняется | editMessageWidgetData | editMessageWidgetData или editSharedWidgetData |
| Примеры | Партия в игре, статус заказа | Результаты опроса, цена |
Оба поля — обычный текст, который сервер никак не интерпретирует; чаще всего там JSON. Если состояния нет или его очистили, в виджете будет null.
Где живут виджеты: продакшен и тестовый сервер
| Где | Как попадает | Запросы (с allow_queries) | Продакшен |
|---|---|---|---|
| Личный чат с ботом | sendWidget, sendSharedWidget | По нажатию и в фоне | Да |
| Обычная группа или супергруппа | sendWidget | Только по нажатию | Только тестовый сервер |
| Любой чат, кроме каналов, через бота | Инлайн-режим (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Только по нажатию | Только тестовый сервер |
| Пересылка, в том числе в каналы | Пересылают пользователи | По нажатию, только общие виджеты | Только тестовый сервер |
Публиковать виджеты в каналах боты не могут. Приложения без поддержки виджетов показывают такое сообщение как неподдерживаемое медиа с подписью. Сообщения с виджетами нельзя скопировать через copyMessage или copyMessages, а в группах на виджеты распространяется право can_send_other_messages.
Виджеты Telegram и Mini Apps: в чём разница
| Параметр | Mini App | Виджет |
|---|---|---|
| Где показывается | В WebView, который открывается по кнопке, из меню или по ссылке | Внутри пузыря сообщения, всегда виден в чате |
| Код | Веб-страница на вашем сервере | До 32 КБ HTML внутри сообщения, фиксируется при отправке |
| Движок | WebView платформы | Песочница QuickJS, рисует приложение Telegram |
| Сеть | Весь интернет | Нет |
| Связь с ботом | Через ваш бэкенд с подписанной initData | TelegramWidget.request() → апдейт widget_query |
| Ввод | Любой, включая клавиатуру | Нажатия и pointer-события, без клавиатуры |
Там, где возможности пересекаются, TelegramWidget повторяет названия из Telegram.WebApp: themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready. Если задача больше, чем помещается в виджет, откройте бота или Mini App через openTelegramLink. А если вы делаете именно Mini App, пригодится гайд как тестировать Telegram Mini App.
Первый виджет через sendWidget
- Создайте бота и скопируйте токен (как создать бота в Telegram, где взять токен бота).
- Отправьте боту
/start, чтобы он мог вам писать, и возьмите свой chat id изgetUpdates. - Вызовите sendWidget. Параметр
html— строка, поэтому удобнее всего отправлять запрос в JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>Ваш промокод</h3><p>Нажмите на кнопку, чтобы скопировать.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "Ваш промокод: PROMO10"
}'
То же самое на Python с requests или на JavaScript с fetch:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Ваш промокод</h3>
<p>Нажмите на кнопку, чтобы скопировать.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "Ваш промокод: PROMO10",
}, timeout=10)
print(r.json()) # result: отправленный Message с полем "widget"const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Ваш промокод</h3>
<p>Нажмите на кнопку, чтобы скопировать.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;
const r = await fetch(`${API}/sendWidget`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: 123456789,
html,
caption: "Ваш промокод: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: отправленный Message с полем "widget"В этом виджете нет ни строчки CSS, но он всё равно выглядит как обычное сообщение с нативной кнопкой. Объект TelegramWidget доступен без всяких тегов script, а copyText срабатывает, потому что вызывается в обработчике нажатия. HTML можно и не отправлять из кода: вставьте его в форму sendWidget в Bot API Tester и отправьте со своим токеном.
Остальные параметры sendWidget: width и height (опорные размеры в логических пикселях), chat_data и public_data (начальное состояние), allow_queries, is_shared, а также привычные подпись, reply_markup, reply_parameters, message_thread_id и protect_content.
Как виджет общается с ботом
Запрос из виджета работает как callback-кнопка, только внутри HTML:
- Бот отправляет виджет с
allow_queries: true. - По нажатию виджет вызывает
TelegramWidget.request("like")с данными длиной 1–64 байта. - Бот получает апдейт
widget_queryс полямиid,from,chat,message_idиdata(из пересланного общего виджета приходитshared_widget_query). Если вы передаётеallowed_updates, укажите оба типа. - Бот в течение 15 секунд вызывает answerWidgetQuery — при желании с
dataдо 1024 байт, которые получит только виджет, отправивший запрос. - Чтобы изменить то, что видят все, бот вызывает editMessageWidgetData (или
editSharedWidgetData), и виджет получаетchatDataChanged/publicDataChanged.
Сам ответ состояние не меняет. Лимит — 5 запросов за 5 секунд на пару «пользователь — бот»; если бот не ответил, виджет получит ошибку TIMEOUT. Полный рабочий код — в гайде примеры виджетов Telegram.
Статичные и общие виджеты
Без is_shared виджет статичный: код и состояние живут в сообщении, а в пересылку уходит замороженная копия. С is_shared первая отправка создаёт общий виджет (shared widget) — один объект с идентификатором (widget.id в возвращённом сообщении), который могут показывать сколько угодно сообщений. Повторно его отправляют через sendSharedWidget, а общее состояние сразу для всех сообщений меняют через editSharedWidgetData — не чаще раза в секунду. Виджет, который уже на экране, получает новое общее состояние, только если вызвал TelegramWidget.watchPublicData(): тогда приложение опрашивает его с периодом обновления виджета (по умолчанию 30 секунд, через cache_time — от 5 до 3600).
Лимиты виджетов Telegram
| Что | Лимит |
|---|---|
| HTML | 32768 байт; 4096 байт после zlib уровня 9 |
chat_data, public_data | По 1024 байта |
| Данные запроса / данные ответа | 1–64 байта / до 1024 байт |
| Время на ответ | 15 секунд |
| Запросы | 5 за 5 секунд на пользователя и бота |
| Размер пузыря | Ширина от 200 px до максимальной ширины пузыря, высота 50–600 px; лишнее обрезается |
| Правки общего виджета | 1 в секунду |
| Память / DOM-узлы | 8 МБ / 2000 узлов |
Полная таблица с квотами CPU, таймерами и хранилищем — в справочнике TelegramWidget API.
Советы по дизайну
- Всегда добавляйте подпись. Именно её показывают список чатов, уведомления, поиск и приложения без поддержки виджетов.
- Используйте тему. Стройте цвета на переменных
--tg-theme-*и проверяйте и светлую, и тёмную тему чата;prefers-color-schemeследует теме чата, а не системы. - Рисуйте первое состояние сразу из
chatData/publicData— загружать нечего. - Держите размер под контролем. Считайте сжатый размер так же, как сервер:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Никаких секретов. Считайте код и общее состояние публичными; в группе состояние чата видит каждый участник.
- Верстайте под ширину через
%, flex или grid.vhне поддерживается, а прокрутки внутри виджета нет. - Показывайте любой исход запроса: «Отправка…», ответ и каждый код ошибки.
Не путайте с виджетами для сайтов
«Виджетом Telegram» называют и более старые виджеты для сайтов: Telegram Login Widget, встраивание постов и кнопку «Поделиться». Это скрипты, которые вы размещаете на своём сайте. Виджеты Bot API 10.4 — совсем другое: это HTML, который бот отправляет в чат. Официальная документация по ним — core.telegram.org/bots/widgets. Как подключить вход через Telegram, встроить пост или кнопку «Поделиться» на сайт, разобрано в гайде виджеты Telegram для сайта.
Что дальше
- Примеры виджетов Telegram: карточка заказа, счётчик с запросами и общий живой опрос — с кодом бота на Python.
- TelegramWidget JavaScript API: свойства, методы, события, коды ошибок, CSS-переменные и лимиты.
- Что нового в Telegram Bot API 10.x: всё остальное, что вошло в версию 10.4.
Частые вопросы
Что такое виджеты Telegram?
Небольшие интерактивные блоки, которые рисуются прямо внутри сообщения бота. Они появились в Bot API 10.4 (9 ноября 2026 года). Виджет — это один самодостаточный HTML-документ со встроенными CSS и JavaScript, который приложение Telegram выполняет на устройстве пользователя в песочнице без доступа к сети.
Работают ли виджеты Telegram в группах?
В продакшене пока нет. Сейчас бот может отправлять виджеты в рабочем окружении только в личный чат с пользователем, и переслать их нельзя. Группы, инлайн-режим и пересылка уже работают на тестовом сервере.
Как отправить виджет из бота?
Вызовите sendWidget с chat_id и html (строка 1–32768 байт, не больше 4096 байт после сжатия zlib уровня 9), по желанию добавьте caption, chat_data, public_data и allow_queries. Метод вернёт отправленный Message с полем widget.
Может ли виджет Telegram делать HTTP-запросы?
Нет. fetch, XMLHttpRequest, WebSocket и любые другие сетевые API выбрасывают NetworkDisabledError. Единственный канал связи — TelegramWidget.request(): он отправляет боту 1–64 байта, и бот получает апдейт widget_query.
Чем виджет отличается от Mini App?
Mini App — это веб-страница на вашем сервере, которая открывается в WebView по кнопке или ссылке и имеет полный доступ к сети. Виджет живёт внутри пузыря сообщения, его HTML размером до 32 КБ фиксируется при отправке, сети у него нет, а общается он только со своим ботом через запросы.
Можно ли изменить HTML виджета после отправки?
Нет. Код фиксируется при отправке, меняется только состояние. Обновляйте chat_data или public_data через editMessageWidgetData или editSharedWidgetData, а для новой вёрстки отправьте новый виджет. Подпись редактируется через editMessageCaption.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.