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-агент. Натискання в картці агента приходить йому як повідомлення контакту.