# HTML-віджет
Блок надсилає віджет — невелику інтерактивну картку просто в повідомленні: опитування, вікторину, калькулятор, таймер, колесо фортуни. Людина натискає в картці, а бот отримує відповідь і йде далі за сценарієм, як після натискання кнопки.
Віджет показується в особистих чатах Telegram і в [чаті на сайті](https://support.watbot.org/uk/chatbots/channels/web). Контакти з інших месенджерів ідуть виходом «Віджет не показано» — з'єднайте його зі звичайним повідомленням.
## З чого почати
У новому блоці панель пропонує три шляхи:
- **«Описати для ШІ»** — відкриється панель [«Створити з ШІ»](https://support.watbot.org/uk/chatbots/blocks#створити-з-ші): опишіть картку словами, і ШІ напише її код і дані.
- **«Писати код»** — відкриється порожній редактор HTML.
- **Шаблон** — готова картка, яку залишиться підписати під себе.
Шаблони: «Голосування», «Оцінка зірками», «Вікторина», «Зворотний відлік», «Кілька відповідей», «Один варіант», «Слайдер», «Колесо фортуни», «Картка лояльності», «Статус замовлення» і «Калькулятор вартості». Після вибору шаблону під полем з'явиться підказка: які відповіді додати і де змінювати тексти. Шаблон можна вибрати й пізніше — кнопка «Шаблони» над редактором. Вибраний шаблон замінює код і дані віджета.
## Налаштування
Код, дані й попередній перегляд — у вкладках над редактором:
- **«HTML-код»** — розмітка, стилі та скрипт віджета. Під полем видно, скільки він важить і скільки після стиснення.
- **«Дані»** — дані цього повідомлення (`chat_data`), до 1024 байт, зазвичай JSON. Віджет читає їх як `TelegramWidget.chatData`. Зручно тримати тут тексти й варіанти, а код залишити спільним.
- **«Попередній перегляд»** — як картка виглядає і працює. Перемикач ☀/☾ змінює світлу й темну тему, «Спочатку» запускає віджет заново. Запити, які віджет надіслав би боту, з'являються під переглядом.
- **«Поруч»** — код і перегляд одночасно. Вкладка розгортає панель [на весь екран](https://support.watbot.org/uk/chatbots/blocks#налаштування-блоку), а під час переходу на іншу вкладку повертає її назад.
Над переглядом — розмір віджета:
- **«Ширина»** — «Авто» (за шириною повідомлення), 320, 400 або «Своя» — від 200 до 600 точок.
- **«Висота»** — «Авто» (за вмістом) або «Своя» — від 50 до 600 точок. Що не вмістилося, обрізається: прокрутки всередині віджета немає.
Нижче редактора:
- **«Підпис»** — текст під віджетом, до 1024 символів.
- **«Відповіді віджета»** — виходи блоку, про них нижче.
- **«Додатково»** — «Записати відповідь в користувацьку змінну» і «Доставляти без звуку», див. [«Додатково»](https://support.watbot.org/uk/chatbots/blocks/messages#додатково).
У коді й даних працюють [автопідстановки](https://support.watbot.org/uk/chatbots/templates): `{{ $name }}` заміниться до надсилання. Попередній перегляд показує код як є, без підстановок.
### Обмеження
- Код — до 32 КБ і до 4 КБ після стиснення. Якщо не вміщується, зберегти можна, але віджет не піде: контакт піде виходом «Віджет не показано», а причина з'явиться в «Лозі виконання».
- Мережі немає: віджет не може завантажити скрипти, стилі, шрифти й картинки за посиланням і не надсилає запити. Картинки — лише вбудованим SVG або `data:`-адресою.
- Дані одного натискання — до 52 байт: близько 25 кириличних літер або 50 латинських.
- Повідомлення з віджетом не можна переслати чи зберегти.
## Відповіді та виходи
Кнопка всередині віджета викликає `TelegramWidget.request('так')` — і контакт іде виходом «так», ніби натиснув кнопку з таким текстом. Цих кнопок контакт не бачить: вони лише пов'язують натискання у віджеті зі сценарієм.
- **Відповіді віджета** — додайте відповідь на кожне значення, яке надсилає віджет.
- **«Будь-яка інша відповідь»** — віджет надіслав значення, якого немає серед відповідей. Щоб зберегти його, увімкніть «Записати відповідь в користувацьку змінну».
- **«Віджет не показано»** — контакт не з Telegram і не з чату на сайті, код більший за ліміт або Telegram відмовився прийняти повідомлення. З'єднайте вихід зі звичайним повідомленням із тим самим змістом.
- **«Продовжити»** — видно лише на схемі: бот іде далі, не чекаючи натискання.
Натискання на старі віджети в історії чату теж приходять у цей блок.
### Відповідь віджету і новий стан
Після виходу сценарій може відповісти віджету — задайте змінні контакту, наприклад блоком «Операція зі змінною» або «Інтерпретатор JavaScript»:
- **`widget_answer`** — що отримає віджет у відповідь на запит: `TelegramWidget.request()` поверне `{ result }` із цим значенням.
- **`widget_chat_data`** — нові дані натиснутого віджета: картка перемалюється в тому ж повідомленні.
Перемалювати картку має сам код віджета: за нових даних платформа надсилає йому подію `chatDataChanged`. Винесіть малювання у функцію та викликайте її і під час завантаження, і за подією — інакше картка залишиться попередньою. Готові шаблони вже так влаштовані.
```js
function render() {
const data = JSON.parse(TelegramWidget.chatData || '{}')
// …
}
render()
TelegramWidget.onEvent('chatDataChanged', render)
```
Оновити віджет пізніше — наприклад, коли замовлення оплачено, — можна блоком [«Оновити HTML-віджет»](https://support.watbot.org/uk/chatbots/blocks/messages/widget-update).
### Голосування й колесо фортуни
Два ключі в даних віджета вмикають готову механіку, сценарій для неї не потрібен:
- **`"poll": ["Так", "Ні"]`** — голосування, до 10 варіантів. Голоси платформа рахує сама: один голос на контакт, повторний змінює вибір. Віджет отримує підсумок: варіанти, кількість голосів і вибір самого контакту.
- **`"prizes": ["Знижка 5%", …]`** — колесо фортуни. Приз обирає платформа: випадково й один раз на контакт.
Обраний варіант або отриманий приз записується в змінну контакту `widget_result` ще до переходу за виходом — його можна одразу підставити в наступне повідомлення: «Ваш приз: {{ $widget_result }}».
## Віджети від AI-агента
AI-агент теж уміє надсилати віджети — увімкніть інструмент «HTML-віджети» в блоці [AI-агент](https://support.watbot.org/uk/chatbots/blocks/ai-agent#інструменти). Натискання в картці агента приходить йому як повідомлення контакту.