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

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

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.