HTML-виджет#

Блок отправляет виджет — небольшую интерактивную карточку прямо в сообщении: опрос, викторину, калькулятор, таймер, колесо фортуны. Человек нажимает в карточке, а бот получает ответ и идёт дальше по сценарию, как после нажатия кнопки.

Виджет показывается в личных чатах Telegram и в чате на сайте. Контакты из других мессенджеров уходят по выходу «Виджет не показан» — соедините его с обычным сообщением.

С чего начать#

В новом блоке панель предлагает три пути:

• «Описать для ИИ» — откроется панель «Создать с ИИ»: опишите карточку словами, и ИИ напишет её код и данные.
• «Писать код» — откроется пустой редактор HTML.
• Шаблон — готовая карточка, которую останется подписать под себя.

Шаблоны: «Голосование», «Оценка звёздами», «Викторина», «Обратный отсчёт», «Несколько ответов», «Один вариант», «Слайдер», «Колесо фортуны», «Карта лояльности», «Статус заказа» и «Калькулятор стоимости». После выбора шаблона под полем появится подсказка: какие ответы добавить и где менять тексты. Шаблон можно выбрать и позже — кнопка «Шаблоны» над редактором. Выбранный шаблон заменяет код и данные виджета.

Настройки#

Код, данные и предпросмотр — во вкладках над редактором:

• «HTML-код» — разметка, стили и скрипт виджета. Под полем видно, сколько он весит и сколько после сжатия.
• «Данные» — данные этого сообщения (chat_data), до 1024 байт, обычно JSON. Виджет читает их как TelegramWidget.chatData. Удобно держать здесь тексты и варианты, а код оставить общим.
• «Предпросмотр» — как карточка выглядит и работает. Переключатель ☀/☾ меняет светлую и тёмную тему, «Сначала» запускает виджет заново. Запросы, которые виджет отправил бы боту, появляются под предпросмотром.
• «Рядом» — код и предпросмотр одновременно. Вкладка разворачивает панель на весь экран, а при переходе на другую вкладку возвращает её обратно.

Над предпросмотром — размер виджета:

• «Ширина» — «Авто» (по ширине сообщения), 320, 400 или «Своя» — от 200 до 600 точек.
• «Высота» — «Авто» (по содержимому) или «Своя» — от 50 до 600 точек. Что не поместилось, обрезается: прокрутки внутри виджета нет.

Ниже редактора:

• «Подпись» — текст под виджетом, до 1024 символов.
• «Ответы виджета» — выходы блока, о них ниже.
• «Дополнительно» — «Записать ответ в пользовательскую переменную» и «Доставлять без звука», см. «Дополнительно».

В коде и данных работают автоподстановки: {{ $name }} заменится до отправки. Предпросмотр показывает код как есть, без подстановок.

Ограничения#

• Код — до 32 КБ и до 4 КБ после сжатия. Если не влезает, сохранить можно, но виджет не уйдёт: контакт пойдёт по выходу «Виджет не показан», а причина появится в «Логе выполнения».
• Сети нет: виджет не может загрузить скрипты, стили, шрифты и картинки по ссылке и не отправляет запросы. Картинки — только встроенным SVG или data:-адресом.
• Данные одного нажатия — до 52 байт: около 25 русских букв или 50 латинских.
• Сообщение с виджетом нельзя переслать или сохранить.

Ответы и выходы#

Кнопка внутри виджета вызывает TelegramWidget.request('да') — и контакт уходит по выходу «да», как если бы нажал кнопку с таким текстом. Эти кнопки контакт не видит: они только связывают нажатия в виджете со сценарием.

• Ответы виджета — добавьте ответ на каждое значение, которое отправляет виджет.
• «Любой другой ответ» — виджет отправил значение, которого нет среди ответов. Чтобы сохранить его, включите «Записать ответ в пользовательскую переменную».
• «Виджет не показан» — контакт не из Telegram и не из чата на сайте, код больше лимита или Telegram отказался принять сообщение. Соедините выход с обычным сообщением с тем же смыслом.
• «Продолжить» — виден только на схеме: бот уходит дальше, не дожидаясь нажатия.

Нажатия на старые виджеты в истории чата тоже приходят в этот блок.

Ответ виджету и новое состояние#

После выхода сценарий может ответить виджету — задайте переменные контакта, например блоком «Операция над переменной» или «Интерпретатор JavaScript»:

• widget_answer — что получит виджет в ответ на запрос: TelegramWidget.request() вернёт { result } с этим значением.
• widget_chat_data — новые данные нажатого виджета: карточка перерисуется в том же сообщении.

Перерисовать карточку должен сам код виджета: при новых данных платформа присылает ему событие chatDataChanged. Вынесите отрисовку в функцию и вызывайте её и при загрузке, и по событию — иначе карточка останется прежней. Готовые шаблоны уже так устроены.

function render() {
    const data = JSON.parse(TelegramWidget.chatData || '{}')
    // …
}
render()
TelegramWidget.onEvent('chatDataChanged', render)

Обновить виджет позже — например, когда заказ оплачен, — можно блоком «Обновить HTML-виджет».

Голосование и колесо фортуны#

Два ключа в данных виджета включают готовую механику, сценарий для неё не нужен:

• "poll": ["Да", "Нет"] — голосование, до 10 вариантов. Голоса платформа считает сама: один голос на контакта, повторный меняет выбор. Виджет получает итог: варианты, число голосов и выбор самого контакта.
• "prizes": ["Скидка 5%", …] — колесо фортуны. Приз выбирает платформа: случайно и один раз на контакта.

Выбранный вариант или выпавший приз записывается в переменную контакта widget_result ещё до перехода по выходу — его можно сразу подставить в следующее сообщение: «Ваш приз: {{ $widget_result }}».

Виджеты от AI-агента#

AI-агент тоже умеет присылать виджеты — включите инструмент «HTML-виджеты» в блоке AI-агент. Нажатие в карточке агента приходит ему как сообщение контакта.