TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
TelegramWidget API — это объект window.TelegramWidget, который каждый виджет Bot API 10.4 получает от приложения Telegram, плюс серверная часть в Bot API: апдейты widget_query и метод answerWidgetQuery. В этом справочнике собраны все свойства, методы, события и коды ошибок TelegramWidget, CSS-переменные, правила жестов и лимиты — по официальной документации по виджетам Telegram.
Доступность: в продакшене виджеты сейчас работают только в личном чате с ботом, и переслать их нельзя (они отправляются с защищённым содержимым). Группы, инлайн-режим и пересылка работают только на тестовом сервере, поэтому свойства вродеisForwardилиchatType: "group"пока важны в первую очередь там.
Впервые слышите о виджетах? Начните с обзора что такое виджеты Telegram и примеров виджетов.
Откуда берётся объект TelegramWidget
Тег script для виджета не нужен. Внутри Telegram window.TelegramWidget существует ещё до запуска первого скрипта виджета. Вне Telegram (в обычном браузере) он равен undefined. Методы, добавленные в рамках профиля, проверяются через typeof:
const W = window.TelegramWidget; // undefined в обычном браузере
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// рисуем по state; null означает «состояния ещё нет»
}
if (W) W.onEvent('chatDataChanged', render);
render();
Свойства TelegramWidget
| Свойство | Тип | Описание |
|---|---|---|
profile | Integer | Профиль виджета, который применяет приложение: в этой версии 1 |
colorScheme | String | light или dark — схема чата (также --tg-color-scheme) |
themeParams | Object | Палитра пузыря в виде строк #rrggbb, с теми же ключами, что themeParams в Mini Apps |
isActive | Boolean | Виджет виден на экране (!document.hidden) |
isPreview | Boolean | Инлайн-результат до отправки: ни нажатий, ни запросов |
isForward | Boolean | Пересланная копия |
chatType | String | private, group, supergroup, channel или null в пересылке и превью |
viewer | Object | id, first_name, last_name, username, is_premium того, кто смотрит; только там, где виджет может отправлять запросы, иначе null |
publicData | String | Общее состояние до 1024 байт или null. Только чтение |
chatData | String | Состояние чата до 1024 байт или null; в пересылке всегда null. Только чтение |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: область, которую закрывает время сообщения |
wallet | Object | Кошелёк Telegram или null (в приложении нет кошелька, запросы запрещены, это превью) |
HapticFeedback | Object | Виброотклик, см. ниже |
Методы TelegramWidget
| Метод | Что делает |
|---|---|
request(data[, options]) | Отправляет боту 1–64 байта. Возвращает Promise с { result } (ответ бота или null) либо отклоняется с WidgetRequestError. Только в обработчике нажатия или в фоне там, где это разрешено. options может быть { wallet: true } |
watchPublicData() / unwatchPublicData() | Включает / выключает живой опрос общего состояния общего виджета, пока он на экране. На статичный виджет и превью не влияет |
copyText(text) | По нажатию копирует 1–256 символов; приложение показывает всплывающее уведомление с текстом |
openLink(url) | Открывает https:-ссылку (≤ 256 символов, не на хосте t.me) после подтверждения пользователем |
openTelegramLink(url) | Открывает ссылку https://t.me/… внутри Telegram, как нажатую ссылку в сообщении |
setResizeAnchor(edge) | top (по умолчанию) или bottom: какой край пузыря остаётся на месте при изменении высоты |
ready() | Необязательно: сообщает приложению, что первое состояние отрисовано |
onEvent(type, handler) / offEvent(type, handler) | Добавить / удалить обработчик события (не больше 16 на тип события) |
isProfileAtLeast(n) | Возвращает profile >= n |
Все методы синхронные, кроме isProfileAtLeast, request и методов кошелька. У HapticFeedback есть impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning) и selectionChanged(). Метода sendMessage нет, а свой widget_id виджет не знает.
События
| Событие | Когда срабатывает |
|---|---|
themeChanged | Сменилась тема чата; colorScheme, themeParams и CSS-переменные уже обновлены |
activated / deactivated | Виджет стал видимым / скрытым (после visibilitychange) |
chatDataChanged | Бот изменил состояние чата; chatData уже новое. В пересылке не срабатывает никогда |
publicDataChanged | Бот изменил общее состояние; для общего виджета на экране — только пока включён watch. Если изменились оба состояния, срабатывает после chatDataChanged |
contentSafeAreaChanged | Изменилась область, которую закрывает время сообщения (подпись добавили, убрали или сдвинули, появилась пометка «изменено») |
Обработчики вызываются без аргументов, а this в них указывает на TelegramWidget, поэтому новые значения читайте из объекта.
Коды WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'Отправка…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'Готово'; },
(error) => { status.textContent = 'Ошибка: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | Значение |
|---|---|
NOT_ALLOWED | Нет allow_queries, пересылка статичного виджета, вызов не по нажатию там, где фоновые запросы выключены, превью или приложение, которое не доставляет запросы |
BUSY | У виджета уже выполняется другой запрос или вызов кошелька |
RATE_LIMITED | Фоновый вызов раньше чем через 5 секунд после предыдущего или больше 5 запросов за 5 секунд на пользователя и бота |
TIMEOUT | Бот не ответил за 15 секунд (лежит, тормозит или не получает widget_query / shared_widget_query) |
FAILED | Всё остальное: бот заблокирован или удалён, сообщения больше нет, сбой сети |
INVALID_ANSWER | Ответ бота нарушил лимиты |
REJECTED, BAD_REQUEST | Только для вызовов кошелька: пользователь отказался или кошелёк отверг транзакцию или payload |
Пустые данные или данные длиннее 64 байт выбрасывают TypeError ещё до отправки.
Серверная часть: widget_query и answerWidgetQuery
Запрос из исходного сообщения приходит в Update как widget_query, из пересланного общего виджета — как shared_widget_query. Если вы передаёте allowed_updates в getUpdates или setWebhook, укажите оба типа.
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
У widget_query из сообщения, отправленного через бота (инлайн-режим), вместо chat и message_id есть inline_message_id и chat_type; для общих виджетов присутствует widget_id. В shared_widget_query есть только id, from, type, data и widget_id. На каждый запрос отвечайте методом answerWidgetQuery (widget_query_id и необязательный data до 1024 байт), а состояние меняйте отдельно через editMessageWidgetData или editSharedWidgetData. Поля from и widget_id заполняет Telegram, подделать их нельзя, но data считайте недоверенным вводом.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
CSS-переменные
| Переменная | Что задаёт |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | Фон пузыря, текст, второстепенный текст, ссылки |
--tg-theme-button-color, --tg-theme-button-text-color | Основная кнопка приложения |
--tg-theme-secondary-bg-color, --tg-theme-accent-text-color, --tg-theme-subtitle-text-color, --tg-theme-destructive-text-color, --tg-theme-section-separator-color | Вторая поверхность, акцент, подзаголовки, опасные действия, разделители |
--tg-color-scheme | light или dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | Размер текста сообщения (около 15px), межстрочный интервал (около 1.35), отступ текста в пузыре (около 8px 12px) |
--tg-button-bg, --tg-button-text, --tg-button-radius, --tg-button-font, --tg-button-padding, --tg-button-height, --tg-button-pressed-opacity, --tg-button-disabled-opacity | Стиль кнопки приложения, который использует <button> по умолчанию |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | Полоса, где рисуется время сообщения (то же, что env(safe-area-inset-*)) |
Приложение задаёт эти переменные на корневом элементе с !important; переопределить их можно только на своих элементах. prefers-color-scheme, light-dark() и color-scheme следуют теме чата, а не системы.
Жесты и touch-action
Нажатия и двойные нажатия всегда достаются виджету, а вертикальные перетаскивания всегда прокручивают чат (виджет получает pointercancel). Долгие нажатия и горизонтальные перетаскивания забираются поэлементно через CSS touch-action: auto оставляет их чату (меню сообщения, свайп для ответа), pan-y отдаёт виджету горизонтальные перетаскивания, none — долгие нажатия (contextmenu) и горизонтальные перетаскивания. Простое правило: touch-action: none на кнопке с удержанием, игровом контроле или canvas, pan-y на горизонтальном слайдере или карусели, auto на всём остальном. Используйте pointer-события — touch-события не доставляются. Не размещайте элементы управления в первых 20 px от начального края: там жесты виджету не отдаются.
Что удаляет профиль виджета
- Элементы форм (
input,select,textarea); единственный элемент управления —<button>. Нет событий клавиатуры и фокуса. - Все сетевые API (
fetch,XMLHttpRequest,WebSocketи другие выбрасываютNetworkDisabledError), внешние скрипты, стили, шрифты и картинки,locationиhistory. vhи другие единицы относительно высоты,overflow: auto / scroll(превращается вhidden),position: sticky,@font-face,:has(), вложенность CSS.alert,confirm,prompt,navigator.clipboard(используйтеcopyText),iframe,video,audio, WebGL.
Удалённые возможности не ломают виджет: элемент, объявление или событие просто отбрасывается, а всё остальное продолжает работать. CSS.supports() и @supports отвечают в соответствии с профилем.
Лимиты виджетов Telegram
| Лимит | Значение | Если превысить |
|---|---|---|
| HTML | 32768 байт; 4096 байт после zlib уровня 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | По 1024 байта UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| Данные запроса | 1–64 байта | TypeError в виджете |
| Данные ответа | 1024 байта | WIDGET_RESULT_TOO_LARGE |
| Время на ответ | 15 секунд | TIMEOUT; запоздавший ответ — query is too old |
| Запросы | 5 за 5 секунд на пользователя и бота | RATE_LIMITED |
| Правки общего виджета | 1 в секунду; период обновления по умолчанию 30 с, cache_time 5–3600 | Flood wait; invalid cache time specified при значении меньше 5 |
| CPU | 300 мс JavaScript в секунду; 500 мс на одну задачу | Замедление; виджет останавливается |
| Память | 8 МБ | Виджет останавливается |
| DOM-узлы | 2000 | Виджет останавливается |
| Таймеры | 64 активных таймера | RangeError |
localStorage, sessionStorage | 4 КБ на область на сообщение | QuotaExceededError |
| Пузырь | Ширина от 200 px до максимальной ширины пузыря, высота 50–600 px | Обрезается |
Остановленный виджет сохраняет последний кадр с плашкой «Widget stopped» и пересоздаётся, когда снова появляется на экране; после двух падений подряд он остаётся остановленным до перезапуска приложения.
Хранилище, ссылки, виброотклик и copyText
- Web Storage принадлежит этому сообщению на этом устройстве. Он переживает перезапуск приложения, никогда не отправляется боту и не синхронизируется между устройствами. Оборачивайте
setItemвtry/catch. - Ссылки:
openLink,openTelegramLink,copyTextиrequestтребуют настоящего нажатия — вызывайте их синхронно в обработчикеclick, а не послеawaitили в таймере. Одно нажатие разрешает один такой вызов. Некорректный URL выбрасываетTypeError; нажатие на<a href="https://…">тоже работает. - Виброотклик срабатывает, только пока виджет виден: не больше 5 подряд и 10 в секунду; во время касания и 5 секунд после него ограничений нет. Десктопные и веб-приложения ничего не воспроизводят.
- copyText копирует 1–256 символов и всегда показывает всплывающее уведомление со скопированным текстом.
Платежи через TON-кошелёк коротко
Виджет может попросить пользователя заплатить через встроенный кошелёк Telegram в форматах TON Connect. Рисуйте кнопку оплаты, только если TelegramWidget.wallet не null. По нажатию виджет отправляет request(data, { wallet: true }); в запросе к боту type будет {"type": "data", "wallet_card": …}, и бот отвечает свежей транзакцией. В обработчике ответа виджет вызывает wallet.sendTransaction() — повторное нажатие в течение 10 секунд для этого не нужно:
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
Затем бот получает запрос типа sent_transaction с хешем сообщения и обязан проверить транзакцию в блокчейне. После TIMEOUT платёж мог и пройти, поэтому спросите бота о статусе заказа, а не платите повторно.
Ошибки Bot API для виджетов
| Ошибка | Причина |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML больше 32768 байт или 4096 байт в сжатом виде |
INPUT_MEDIA_WIDGET_HTML_INVALID | Некорректный UTF-8 или символ NUL в html |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data или public_data больше 1024 байт |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | Некорректный текст состояния при отправке / при редактировании |
message is not modified | Правка ничего не меняет; считайте её успехом |
Попробуйте методы со своим токеном в Bot API Tester и посмотрите параметры sendWidget в справочнике. Полный список изменений версии 10.4 — в обзоре что нового в Telegram Bot API 10, а про «старшего брата» виджетов — в гайде как тестировать Telegram Mini App.
Частые вопросы
Нужно ли подключать скрипт, чтобы пользоваться TelegramWidget?
Нет. Внутри Telegram window.TelegramWidget существует ещё до запуска первого скрипта виджета, и состояние, тема и контекст в нём уже заполнены. Вне Telegram он равен undefined, так что проверяйте его наличие, если открываете виджет в браузере.
Что означает ошибка WidgetRequestError NOT_ALLOWED?
Это сообщение не может отправлять запросы: виджет отправлен без allow_queries, это пересылка статичного виджета или превью, либо request() вызван не по нажатию там, где фоновые запросы запрещены.
За сколько бот должен ответить на widget_query?
За 15 секунд, методом answerWidgetQuery. После этого промис в виджете отклоняется с TIMEOUT, а запоздавший ответ отвергается с ошибкой query is too old. Отвечайте на каждый запрос, даже если что-то пошло не так.
Может ли виджет сам изменить chatData или publicData?
Нет. В виджете оба поля доступны только для чтения. Состояние пишет только бот — через sendWidget, editMessageWidgetData или editSharedWidgetData; виджет может лишь попросить бота через TelegramWidget.request().
Есть ли у TelegramWidget метод sendMessage?
Нет. sendMessage в виджетах не существует: от имени пользователя в чат никогда ничего не отправляется. Виджет умеет только отправлять запросы своему боту, копировать текст, открывать ссылки и включать виброотклик.
Читайте также
Как создать бота в Телеграм: от @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, встраивание постов, комментарии и кнопка «Поделиться».
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.