Telegram Bot API

TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты

· 10 мин чтения

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

СвойствоТипОписание
profileIntegerПрофиль виджета, который применяет приложение: в этой версии 1
colorSchemeStringlight или dark — схема чата (также --tg-color-scheme)
themeParamsObjectПалитра пузыря в виде строк #rrggbb, с теми же ключами, что themeParams в Mini Apps
isActiveBooleanВиджет виден на экране (!document.hidden)
isPreviewBooleanИнлайн-результат до отправки: ни нажатий, ни запросов
isForwardBooleanПересланная копия
chatTypeStringprivate, group, supergroup, channel или null в пересылке и превью
viewerObjectid, first_name, last_name, username, is_premium того, кто смотрит; только там, где виджет может отправлять запросы, иначе null
publicDataStringОбщее состояние до 1024 байт или null. Только чтение
chatDataStringСостояние чата до 1024 байт или null; в пересылке всегда null. Только чтение
contentSafeAreaInsetObjecttop, right, bottom, left, cornerLeft, cornerRight: область, которую закрывает время сообщения
walletObjectКошелёк Telegram или null (в приложении нет кошелька, запросы запрещены, это превью)
HapticFeedbackObjectВиброотклик, см. ниже

Методы 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-schemelight или 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 от начального края: там жесты виджету не отдаются.

Что удаляет профиль виджета

Удалённые возможности не ломают виджет: элемент, объявление или событие просто отбрасывается, а всё остальное продолжает работать. CSS.supports() и @supports отвечают в соответствии с профилем.

Лимиты виджетов Telegram

ЛимитЗначениеЕсли превысить
HTML32768 байт; 4096 байт после zlib уровня 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_dataПо 1024 байта UTF-8INPUT_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–3600Flood wait; invalid cache time specified при значении меньше 5
CPU300 мс JavaScript в секунду; 500 мс на одну задачуЗамедление; виджет останавливается
Память8 МБВиджет останавливается
DOM-узлы2000Виджет останавливается
Таймеры64 активных таймераRangeError
localStorage, sessionStorage4 КБ на область на сообщениеQuotaExceededError
ПузырьШирина от 200 px до максимальной ширины пузыря, высота 50–600 pxОбрезается

Остановленный виджет сохраняет последний кадр с плашкой «Widget stopped» и пересоздаётся, когда снова появляется на экране; после двух падений подряд он остаётся остановленным до перезапуска приложения.

Платежи через 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_LARGEHTML больше 32768 байт или 4096 байт в сжатом виде
INPUT_MEDIA_WIDGET_HTML_INVALIDНекорректный UTF-8 или символ NUL в html
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_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.