Веб-виджеты Telegram

Веб-виджет — маленькое приложение прямо в сообщении бота: опрос с живыми процентами, карточка товара с кнопками, таймер акции, промокод, калькулятор. Telegram рисует его в самом пузыре чата на iPhone, Android, компьютере и в веб-версии, в цветах темы человека. Это возможность Bot API 10.4; в конструкторе за неё отвечает блок «Виджет».

Как добавить виджет

  1. Откройте сценарий бота из конструктора и перетащите блок «Виджет» на схему.
  2. Выберите готовый виджет и заполните поля — превью справа обновляется сразу. В полях работают переменные: {{user_name}}, личный промокод из {{promo}} и так далее.
  3. Если виджет что-то спрашивает (опрос, оценка, карточка с кнопками), укажите переменную для ответа и блок, куда идти после выбора. Ветвить по ответу удобно блоком «Условие».
  4. Опубликуйте сценарий.

Готовые виджеты

ВиджетЧто делаетЖдёт выбора
Опросвопрос и до 6 вариантов; голоса считает платформа, проценты обновляются у всех, даже в пересланных копияхда
Оценка звёздами1–5 звёзд, оценка — в переменнуюда
Промокодскидка крупно, условия, код с кнопкой «Скопировать» и ссылка на сайтнет
Таймеробратный отсчёт до даты и времени по Москве, потом ваш текстнет
Карточка товараназвание, цена и старая цена, описание, до 4 плюсов и до 3 кнопокда

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

Свой виджет

Выберите «Свой виджет» и вставьте HTML или опишите виджет словами — ИИ напишет код, уложит его в лимиты и предложит текст для мессенджеров без виджетов (сборка с ИИ — с тарифа «Про»). Правки тоже словами: «сделай кнопки крупнее», «добавь третий вариант».

Правила, по которым Telegram показывает виджет:

  • один файл: разметка, <style> и <script>; не больше 32 КБ HTML и 4 КБ после сжатия — счётчик под превью считает так же, как сервер Telegram;
  • сети нет: внешние картинки, шрифты, скрипты, fetch не работают; картинки — только data:;
  • полей ввода нет (input, select, textarea удаляются), только нажатия;
  • ширина пузыря 200–600 px, высота до 600 px, прокрутки внутри нет;
  • цвета берите из темы чата: var(--tg-theme-text-color), var(--tg-theme-button-color) и другие.

Чтобы выбор ушёл боту, виджет вызывает TelegramWidget.request('pick:0') по нажатию: pick:0 — первая строка в поле «Варианты выбора», pick:1 — вторая и так далее. Значение попадает в переменную блока, и сценарий идёт дальше. Подробные правила и примеры — в репозитории Telegram widget-sandbox.

Где виджет не показывается

  • VK, MAX и Avito виджетов не умеют: человек получит обычное сообщение с тем же текстом и кнопками вариантов, а выбор работает так же.
  • Старые версии Telegram покажут подпись под виджетом и заглушку «Виджет».
  • Если Telegram ещё не включил виджеты вашему боту, платформа отправит сообщение с кнопками и один раз в час напишет об этом в журнал бота. Как только Telegram откроет sendWidget, виджеты пойдут сами — сценарий менять не нужно.

Тестовый чат

В тестовом чате редактора виджет показывается примерно так, как в Telegram: нажатие в нём ведёт сценарий дальше, как настоящее. Под ним — кнопки, которые увидят в VK и MAX. Точный вид зависит от приложения Telegram.

Виджет под ключ

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