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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.