Что такое виджеты Telegram
Виджет — небольшой интерактивный блок, который бот рисует прямо внутри сообщения: опрос, в котором полосы двигаются, пока люди голосуют; промокод, который копируется по нажатию; таймер до события. Виджеты появились в Bot API 10.4 в ноябре 2026 года.
Технически виджет — один HTML-документ со встроенными CSS и JavaScript: не больше 32 768 байт и не больше 4 096 байт после сжатия. Приложение Telegram выполняет его на устройстве человека в песочнице, у которой нет доступа к сети, и рисует в стиле чата.
Код и состояние
Виджет — это неизменный код плюс изменяемое состояние.
- Код задаётся при отправке и больше не меняется. Чтобы изменить вёрстку, нужно отправить новый виджет; в старых сообщениях останется старый.
- Состояние чата (
chat_data) привязано к одному сообщению и видно только в этом чате: «вы уже проголосовали», «ваш промокод». - Общее состояние (
public_data) видно везде, где показан виджет: результаты опроса, число участников розыгрыша.
Состояние пишет только бот. Виджет читает его и перерисовывается, а изменить может только одним способом — попросить бота коротким запросом до 64 байт, как это делает кнопка под сообщением. На запрос бот должен ответить за 15 секунд.
Статический и общий виджет
Статический виджет хранит код и состояние в самом сообщении. Общий (shared) — это один объект на сервере Telegram, который показывает сколько угодно сообщений: когда бот меняет его общее состояние, изменение доходит до всех. Так устроен опрос с живыми результатами.
Где работают виджеты
Telegram включает виджеты по частям. По документации, в боевой среде они сейчас работают только в личном чате с ботом; группы, инлайн-режим и пересылки — пока только на тестовом сервере Telegram. В каналы виджет отправить нельзя.
| Где | Как попадает | В боевой среде |
|---|---|---|
| Личный чат с ботом | бот отправляет виджет | Да |
| Группа, где есть бот | бот отправляет виджет | Только тестовый сервер |
| Любой чат, кроме каналов | через бота в инлайн-режиме | Только тестовый сервер |
| Пересылка в любой чат | пересылают сами люди | Только тестовый сервер |
Поэтому главный способ распространения сегодня — ссылка на бота: её ставят под постом в канале или отправляют в чат, человек нажимает «Запустить» и получает виджет в личном чате.
Чем виджет отличается от Mini App
| Mini App | Виджет | |
|---|---|---|
| Где | отдельное окно, открывается по кнопке или ссылке | внутри пузыря сообщения, всегда на виду |
| Код | веб-страница на вашем сервере | до 32 КБ HTML внутри сообщения, после отправки не меняется |
| Сеть | обычный интернет | нет совсем |
| Связь с ботом | ваш сервер | короткий запрос через Telegram |
| Ввод | любой, с клавиатурой | нажатия и жесты; клавиатуры и полей ввода нет |
Что берёт на себя Widgram
- Код. Готовые шаблоны, уложенные в лимит размера и проверенные по профилю виджета. Вы меняете только настройки.
- Сервер. Мы принимаем запросы виджета, считаем голоса, выдаём промокоды, проводим розыгрыши и обновляем состояние.
- Проверку. Эмулятор показывает виджет в пузыре сообщения: темы, ширина, размер текста.
Дальше: как пользоваться конструктором и ограничения платформы.
Источник: официальное руководство Telegram по виджетам. Правила задаёт Telegram и может их менять; если эта страница расходится с руководством, верно руководство.