# HTML-виджет
Блок отправляет виджет — небольшую интерактивную карточку прямо в сообщении: опрос, викторину, калькулятор, таймер, колесо фортуны. Человек нажимает в карточке, а бот получает ответ и идёт дальше по сценарию, как после нажатия кнопки.
Виджет показывается в личных чатах Telegram и в [чате на сайте](https://support.watbot.ru/chatbots/channels/web). Контакты из других мессенджеров уходят по выходу «Виджет не показан» — соедините его с обычным сообщением.
## С чего начать
В новом блоке панель предлагает три пути:
- **«Описать для ИИ»** — откроется панель [«Создать с ИИ»](https://support.watbot.ru/chatbots/blocks#создать-с-ии): опишите карточку словами, и ИИ напишет её код и данные.
- **«Писать код»** — откроется пустой редактор HTML.
- **Шаблон** — готовая карточка, которую останется подписать под себя.
Шаблоны: «Голосование», «Оценка звёздами», «Викторина», «Обратный отсчёт», «Несколько ответов», «Один вариант», «Слайдер», «Колесо фортуны», «Карта лояльности», «Статус заказа» и «Калькулятор стоимости». После выбора шаблона под полем появится подсказка: какие ответы добавить и где менять тексты. Шаблон можно выбрать и позже — кнопка «Шаблоны» над редактором. Выбранный шаблон заменяет код и данные виджета.
## Настройки
Код, данные и предпросмотр — во вкладках над редактором:
- **«HTML-код»** — разметка, стили и скрипт виджета. Под полем видно, сколько он весит и сколько после сжатия.
- **«Данные»** — данные этого сообщения (`chat_data`), до 1024 байт, обычно JSON. Виджет читает их как `TelegramWidget.chatData`. Удобно держать здесь тексты и варианты, а код оставить общим.
- **«Предпросмотр»** — как карточка выглядит и работает. Переключатель ☀/☾ меняет светлую и тёмную тему, «Сначала» запускает виджет заново. Запросы, которые виджет отправил бы боту, появляются под предпросмотром.
- **«Рядом»** — код и предпросмотр одновременно. Вкладка разворачивает панель [на весь экран](https://support.watbot.ru/chatbots/blocks#настройки-блока), а при переходе на другую вкладку возвращает её обратно.
Над предпросмотром — размер виджета:
- **«Ширина»** — «Авто» (по ширине сообщения), 320, 400 или «Своя» — от 200 до 600 точек.
- **«Высота»** — «Авто» (по содержимому) или «Своя» — от 50 до 600 точек. Что не поместилось, обрезается: прокрутки внутри виджета нет.
Ниже редактора:
- **«Подпись»** — текст под виджетом, до 1024 символов.
- **«Ответы виджета»** — выходы блока, о них ниже.
- **«Дополнительно»** — «Записать ответ в пользовательскую переменную» и «Доставлять без звука», см. [«Дополнительно»](https://support.watbot.ru/chatbots/blocks/messages#дополнительно).
В коде и данных работают [автоподстановки](https://support.watbot.ru/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.ru/chatbots/blocks/messages/widget-update).
### Голосование и колесо фортуны
Два ключа в данных виджета включают готовую механику, сценарий для неё не нужен:
- **`"poll": ["Да", "Нет"]`** — голосование, до 10 вариантов. Голоса платформа считает сама: один голос на контакта, повторный меняет выбор. Виджет получает итог: варианты, число голосов и выбор самого контакта.
- **`"prizes": ["Скидка 5%", …]`** — колесо фортуны. Приз выбирает платформа: случайно и один раз на контакта.
Выбранный вариант или выпавший приз записывается в переменную контакта `widget_result` ещё до перехода по выходу — его можно сразу подставить в следующее сообщение: «Ваш приз: {{ $widget_result }}».
## Виджеты от AI-агента
AI-агент тоже умеет присылать виджеты — включите инструмент «HTML-виджеты» в блоке [AI-агент](https://support.watbot.ru/chatbots/blocks/ai-agent#инструменты). Нажатие в карточке агента приходит ему как сообщение контакта.