Telegram Bot API

Виджеты Telegram: интерактивный HTML прямо в сообщениях бота

· 8 мин чтения

Виджеты Telegram — это небольшие интерактивные HTML-блоки, которые бот отправляет внутри сообщения методом sendWidget. Они появились в Bot API 10.4 9 ноября 2026 года. Виджет — один HTML-документ размером до 32 КБ: приложение Telegram выполняет его на устройстве пользователя без доступа к сети и рисует в стиле чата. Это может быть карточка заказа с обновляемым статусом, счётчик, опрос с живыми полосками результатов или промокод, который копируется одним нажатием.

Где виджеты работают сейчас: в продакшене бот может отправлять виджеты только в личный чат с пользователем, причём такие сообщения отправляются с защищённым содержимым, поэтому переслать их нельзя. Виджеты в группах, в инлайн-режиме и в пересылках пока работают только на тестовом сервере.

Что такое виджет Telegram

Код и состояние: chat_data и public_data

Виджет — это неизменяемый код плюс изменяемое состояние. HTML задаётся при отправке и больше не меняется: метода, который бы его заменил, нет. Меняется только состояние, и пишет его исключительно бот. Виджет читает его из TelegramWidget.chatData и TelegramWidget.publicData и перерисовывается по событиям chatDataChanged и publicDataChanged.

ПараметрСостояние чата (chat_data)Общее состояние (public_data)
К чему привязаноК одному исходному сообщениюК сообщению статичного виджета или к общему виджету везде, где он показан
Кто видитТолько в этом чате (в группе — одно на всех участников)Везде, где показан виджет
В пересылкеНикогдаКопия (статичный виджет) или живое общее состояние (общий виджет)
РазмерДо 1024 байт текстаДо 1024 байт текста
Чем меняетсяeditMessageWidgetDataeditMessageWidgetData или 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
СетьВесь интернетНет
Связь с ботомЧерез ваш бэкенд с подписанной initDataTelegramWidget.request() → апдейт widget_query
ВводЛюбой, включая клавиатуруНажатия и pointer-события, без клавиатуры

Там, где возможности пересекаются, TelegramWidget повторяет названия из Telegram.WebApp: themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready. Если задача больше, чем помещается в виджет, откройте бота или Mini App через openTelegramLink. А если вы делаете именно Mini App, пригодится гайд как тестировать Telegram Mini App.

Первый виджет через sendWidget

  1. Создайте бота и скопируйте токен (как создать бота в Telegram, где взять токен бота).
  2. Отправьте боту /start, чтобы он мог вам писать, и возьмите свой chat id из getUpdates.
  3. Вызовите 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:

  1. Бот отправляет виджет с allow_queries: true.
  2. По нажатию виджет вызывает TelegramWidget.request("like") с данными длиной 1–64 байта.
  3. Бот получает апдейт widget_query с полями id, from, chat, message_id и data (из пересланного общего виджета приходит shared_widget_query). Если вы передаёте allowed_updates, укажите оба типа.
  4. Бот в течение 15 секунд вызывает answerWidgetQuery — при желании с data до 1024 байт, которые получит только виджет, отправивший запрос.
  5. Чтобы изменить то, что видят все, бот вызывает 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

ЧтоЛимит
HTML32768 байт; 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.

Советы по дизайну

Не путайте с виджетами для сайтов

«Виджетом Telegram» называют и более старые виджеты для сайтов: Telegram Login Widget, встраивание постов и кнопку «Поделиться». Это скрипты, которые вы размещаете на своём сайте. Виджеты Bot API 10.4 — совсем другое: это HTML, который бот отправляет в чат. Официальная документация по ним — core.telegram.org/bots/widgets. Как подключить вход через Telegram, встроить пост или кнопку «Поделиться» на сайт, разобрано в гайде виджеты Telegram для сайта.

Что дальше

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

Что такое виджеты 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.