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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: 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.