Віджети Telegram: інтерактивний HTML просто в повідомленнях бота
Віджети Telegram — це невеликі інтерактивні HTML-блоки, які бот надсилає всередині повідомлення методом sendWidget. Вони з'явилися в Bot API 10.4 9 листопада 2026. Віджет — один HTML-документ розміром до 32 КБ: застосунок Telegram виконує його на пристрої користувача без доступу до мережі й малює в стилі чату. Це може бути картка замовлення зі статусом, що оновлюється, лічильник, опитування з живими смужками результатів або промокод, який копіюється одним дотиком.
Де віджети працюють зараз: у продакшені бот може надсилати віджети лише в особистий чат із користувачем, причому такі повідомлення надсилаються із захищеним вмістом, тож переслати їх не можна. Віджети в групах, в інлайн-режимі та в пересиланнях поки що працюють лише на тестовому сервері.
Що таке віджет Telegram
- Один HTML-документ. Стилі й скрипти — лише вбудовані (
<style>і<script>), зображення — лише якdata:-URL або inline SVG. Не більше 32768 байтів у UTF-8 і не більше 4096 байтів після стиснення zlib рівня 9. Обгортка<html>і<body>не обов'язкова — достатньо фрагмента. - Пісочниця. JavaScript виконується в QuickJS — компактному JS-рушії, а не у WebView. Застосунок перевіряє кожну зміну, яку робить віджет, на відповідність профілю віджета й малює лише те, що пройшло перевірку. Тому віджет виглядає однаково на iOS, Android, macOS, у Telegram Desktop і у вебверсії.
- Без мережі.
fetch,XMLHttpRequest,WebSocketта інші мережеві API викидаютьNetworkDisabledError. Зовнішні скрипти, стилі, шрифти й зображення ніколи не завантажуються, вбудованих бібліотек теж немає. - Нативний вигляд. Палітра чату доступна в CSS-змінних
--tg-theme-*, а<button>без стилів малюється як рідна кнопка застосунку. - Без клавіатури. Поля введення, випадні списки й textarea видаляються. Віджет реагує на дотики, pointer-події, горизонтальні перетягування та довгі натискання.
Код і стан: chat_data та public_data
Віджет — це незмінний код плюс змінний стан. HTML задається під час надсилання й більше не змінюється: методу, який би його замінив, немає. Змінюється лише стан, і записує його виключно бот. Віджет читає його з TelegramWidget.chatData і TelegramWidget.publicData та перемальовується за подіями chatDataChanged і publicDataChanged.
| Параметр | Стан чату (chat_data) | Спільний стан (public_data) |
|---|---|---|
| До чого прив'язаний | До одного вихідного повідомлення | До повідомлення статичного віджета або до спільного віджета скрізь, де він показаний |
| Хто бачить | Лише в цьому чаті (у групі — один на всіх учасників) | Скрізь, де показано віджет |
| У пересиланні | Ніколи | Копія (статичний віджет) або живий спільний стан (спільний віджет) |
| Розмір | До 1024 байтів тексту | До 1024 байтів тексту |
| Чим змінюється | editMessageWidgetData | editMessageWidgetData або 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 |
| Мережа | Увесь інтернет | Немає |
| Зв'язок із ботом | Через ваш бекенд із підписаною initData | TelegramWidget.request() → апдейт widget_query |
| Введення | Будь-яке, зокрема клавіатура | Дотики й pointer-події, без клавіатури |
Там, де можливості перетинаються, TelegramWidget повторює назви з Telegram.WebApp: themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready. Якщо задача більша, ніж уміщується у віджет, відкрийте бота або Mini App через openTelegramLink. А якщо ви робите саме Mini App, стане в пригоді гайд тестування Telegram Mini App.
Перший віджет через sendWidget
- Створіть бота й скопіюйте токен (як створити бота в Telegram, як отримати токен бота).
- Надішліть боту
/start, щоб він міг вам писати, і візьміть свій chat id зgetUpdates. - Викличте 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:
- Бот надсилає віджет з
allow_queries: true. - За дотиком віджет викликає
TelegramWidget.request("like")з даними завдовжки 1–64 байти. - Бот отримує апдейт
widget_queryз полямиid,from,chat,message_idіdata(з пересланого спільного віджета надходитьshared_widget_query). Якщо ви передаєтеallowed_updates, вкажіть обидва типи. - Бот протягом 15 секунд викликає answerWidgetQuery — за бажанням із
dataдо 1024 байтів, які отримає лише віджет, що надіслав запит. - Щоб змінити те, що бачать усі, бот викликає 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
| Що | Ліміт |
|---|---|
| HTML | 32768 байтів; 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.
Поради щодо дизайну
- Завжди додавайте підпис. Саме його показують список чатів, сповіщення, пошук і застосунки без підтримки віджетів.
- Використовуйте тему. Будуйте кольори на змінних
--tg-theme-*і перевіряйте як світлу, так і темну тему чату;prefers-color-schemeвідповідає темі чату, а не системи. - Малюйте перший стан одразу з
chatData/publicData— завантажувати нічого. - Тримайте розмір під контролем. Рахуйте стиснений розмір так само, як сервер:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Жодних секретів. Вважайте код і спільний стан публічними; у групі стан чату бачить кожен учасник.
- Верстайте під ширину через
%, flex або grid.vhне підтримується, а прокручування всередині віджета немає. - Показуйте будь-який результат запиту: «Надсилання…», відповідь і кожен код помилки.
Не плутайте з віджетами для сайтів
«Віджетом Telegram» називають і старіші віджети для сайтів: Telegram Login Widget, вбудовування дописів і кнопку «Поділитися». Це скрипти, які ви розміщуєте на своєму сайті. Віджети Bot API 10.4 — зовсім інше: це HTML, який бот надсилає в чат. Офіційна документація щодо них — core.telegram.org/bots/widgets. Як підключити вхід через Telegram, вбудувати допис або кнопку «Поділитися» на сайт, розібрано в гайді віджети Telegram для сайту.
Що далі
- Приклади віджетів Telegram: картка замовлення, лічильник із запитами та спільне живе опитування — з кодом бота на Python.
- TelegramWidget JavaScript API: властивості, методи, події, коди помилок, CSS-змінні та ліміти.
- Що нового в Telegram Bot API 10.x: усе інше, що увійшло у версію 10.4.
Поширені запитання
Що таке віджети 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.