Виджет в Telegram: что это и чем отличается от мини-аппа
Содержание
Виджет в Telegram это маленькое приложение прямо в сообщении: бот присылает живую программу, и она работает в чате. Ближайший аналог: Live Activities у Apple, карточка на экране блокировки iPhone, когда заказываешь такси или пиццу. Карточка в чате обновляется сама и отвечает на нажатия. Мини-апп, приложение в окне поверх чата, открывать не нужно.
Пока виджеты работают через бета-адрес Bot API, интерфейса, которым программа управляет ботом. Я попросил агента, и он собрал аквариум, панель и две версии игры. Каждый виджет укладывается в лимит 4 КБ после сжатия. Всё это лежит в скилле, наборе инструкций для агента: tg-widgets из открытой библиотеки telegram-skills. Ставите его своему агенту и просите виджет словами.
На 6 ноября виджет сработал только в личке с ботом. В канал и группу его пока не отправить: канал, супергруппа и группа комментариев отказали.
Попробовать: откройте бота с телефона, он пришлёт аквариум и игру в личку. Если не открылось, обновите Telegram.
Интерфейс Telegram и окно агента в ролике нарисованы. Виджеты настоящие: тот же код, что бот присылает в личку.
Что такое виджет в сообщении
Обычное сообщение показывает текст или картинку и больше ничего не делает. Виджет выглядит как такое же сообщение, только внутри работает маленькая веб-страница. Она сама рисует, двигает картинку и отвечает на нажатия. Окно не открывается.
В публичной документации Bot API виджетов пока нет. Описание лежит в репозитории самого Telegram: там это виджеты и метод sendWidget. Правила для авторов собраны в отдельном руководстве. По репозиторию это версия Bot API 10.4. Метод отвечает только по адресу https://api.telegram.org/beta/bot<token>/. Названия ещё могут поменяться. В первых бета-сборках для macOS встречалось неофициальное имя HTMLBubbles, его подхватили kod.ru и каналы про беты.
Рамки жёсткие:
| Что | Предел |
|---|---|
| Размер | 4096 байт после zlib (сжатие данных, как в архиве) |
| Ширина | от 200 до 600 px |
| Высота | до 600 px |
| Процессор | 300 мс работы в секунду |
| Запрещено | сеть, WebGL (быстрая графика через видеокарту), библиотеки |
Скачать ничего нельзя. Всё, что виджет показывает, он приносит с собой или генерирует на месте.
Чем виджет отличается от мини-аппа
Мини-апп это сайт внутри Telegram: окно поверх чата, кабинет, каталог, форма. Виджет закрывает один шаг прямо в переписке: квиз, выбор времени, статус заказа.
| Мини-апп | Виджет | |
|---|---|---|
| Где открывается | окно поверх чата | внутри сообщения |
| Запуск | грузится с сервера | сразу, код уже в сообщении |
| Сервер для показа | нужен | не нужен |
| Сеть и ввод текста | есть | нет, только нажатия |
| Для чего | кабинет, каталог | один шаг в переписке |
Live Activities появляются на экране блокировки, и для них нужно приложение под iPhone. Виджет приходит в чат от бота, клиенту ставить ничего не надо.
Как виджет получает данные без сети
Виджет вроде калькулятора считает внутри сообщения. Всё остальное идёт через бота:
- Виджет отправляет боту запрос до 64 байт: например, выбранное время записи.
- Бот отвечает и, например, записывает время в свою CRM или календарь.
- Бот меняет состояние виджета методом
editMessageWidgetData, и карточка обновляется без нового сообщения и уведомления.
Запрос и обновление описаны в документации Telegram, CRM здесь мой пример. Живьём я проверял показ виджетов и отправку, этот обмен с ботом ещё нет.
Зачем виджет бизнесу: шесть примеров
В ролике шесть сценариев, как было и как стало, от кнопки «Запустить» до ответа бота, и сравнение с мини-аппом. Ролик нарисован. Онлайн-школа в нём мой Кружок вайбкодинга, пиццерия, барбершоп, магазин, кофейня и B2B-услуги придуманы.
| Бизнес | Как было | Как стало |
|---|---|---|
| Онлайн-школа | 4 сообщения с вопросами | квиз в 1 сообщении |
| Доставка | 4 уведомления | 1 карточка, статус обновляется |
| Салон | переписка о времени | выбор дня и времени на одном экране |
| Магазин | вопросы по очереди | цвет и размер на одном экране |
| Кофейня | команда в чате | карта всегда под рукой |
| B2B-услуги | созвон и КП | цифра сразу, заявка менеджеру |
Где виджет работает сегодня: только личка
6 ноября я попросил агента проверить отправку живьём, через моего бота. Inline-режим в таблице: бота зовут прямо из строки ввода чата.
| Куда | Результат |
|---|---|
| Личка с ботом | работает, отображается на моём iPhone |
| Канал напрямую | отказ |
| Канал пересылкой и копированием | отказ |
| Inline-режим в канале и из лички с ботом | answerInlineQuery отвечает INPUT_MEDIA_WIDGET_NOT_ALLOWED |
| Супергруппа и группа комментариев канала | та же ошибка, хотя описание в репозитории разрешает |
Пост с игрой в канале сегодня не сделать. Рабочий маршрут: пост с роликом и ссылкой на бота, а виджет приходит в личку.
Успешный ответ сервера не значит, что человек увидел виджет: старые версии Telegram показывают заглушку с подписью. Поэтому пишите подпись, понятную без виджета.
Замер на компьютере не предсказывает телефон
Внешний вид мы искали на телефоне: агент собирал версию, я смотрел её на iPhone. Заходов было три.
Сначала агент нарисовал плоскую векторную графику с градиентами, на полном разрешении. На iPhone она тормозила, и я написал агенту: «Отпратный стиль примитная графика плохие цвета и тормозит».
Потом агент собрал ASCII, рисунок буквами, на семи текстовых слоях. Браузер на компьютере, замедленный в четыре раза, показал 89 мс процессора в секунду при лимите 300. На iPhone версия тормозила и теряла слои.
Третий заход: агент нарисовал всё на canvas, холсте для рисования на странице. Разрешение низкое, примерно 130 точек в ширину. Шрифт пиксельный, 5×5. Переход цвета передаёт дизеринг: узор из точек. Мой ответ на эту версию: «Супер. Оч круто».
Снято на iPhone в личке с ботом: ранняя версия аквариума.
Замер на компьютере годится, чтобы сравнивать версии одного способа рисования. Ответ про телефон даёт только телефон.
Что поместилось в 4 КБ
Код может весить больше лимита, потому что лимит считается после сжатия.
| Виджет | Код | После zlib |
|---|---|---|
| Аквариум | 7,6 КБ | 4080 байт |
| Панель в текстовом режиме | 3,8 КБ | 2134 байта |
| «Ночной деплой», пиксельная версия | 7,1 КБ | 4086 байт |
| «Ночной деплой», текстовая версия | 7,4 КБ | 4071 байт |
Аквариум. Зерно: случайное число, из которого код строит аквариум. Оно хранится на устройстве зрителя, поэтому у каждого зрителя свой цвет воды, свои камни, кораллы и рыбы. После 8 секунд без нажатий появляется заставка АКВАРИУМ.ЕХЕ и надпись ПОКОРМИ РЫБОК. Кнопка «+РЫБА» в кадре была, я забраковал её как антиэстетику.
Кадры из браузера: шесть зёрен дают шесть разных аквариумов из одного кода.
Панель. Текстовый режим, стиль вдохновлён ASCII-демо Plasma Андреаса Гисина. Буквы тут нарисованы на canvas, такая сетка знаков на iPhone прошла. Я и аналитику смотрю в ASCII-дашбордах, так что этот вид мне близок.
Кадр из браузера: панель в текстовом режиме, поле «кольца».
«Ночной деплой». Оригинальная игра в жанре survivors: толпы врагов, босс, прокачка на выбор. Две версии в кадре 16:9. Ради размера из пиксельной вырезано два оружия из четырёх. Вертикальный жест в виджете всегда прокручивает чат, поэтому джойстик тут не сделать.
Сжатие: хватило terser и zlib
Лимит считается после zlib, и это ломает привычные приёмы конкурсов маленьких программ. Агент проверил упаковщики, программы для ужимания кода. Рабочая цепочка вышла короткая: terser ужимает код, zlib сжимает результат.
RegPack заменяет повторы в коде короткими метками, а zlib и сам хорошо сжимает повторы. На тесте с пинболом Фрэнка Форса RegPack дал 862 байта после zlib. Код, ужатый вручную, дал 741, RegPack на 16% хуже. Другой упаковщик, Roadroller, распаковывался в нашем замере на компьютере от 2,1 до 2,3 секунды при лимите 300 мс в секунду.
Русские строки сжимаются плохо. Короткие надписи дали больше, чем переименование переменных: переименование принесло около 40 байт из 4300.
Как поставить скилл своему агенту
В скилле правила из документации Telegram, таблица, куда виджет доходит, лимиты, список того, что виджету недоступно, четыре примера и скрипт. Скрипт меряет размер так же, как сервер, и отправляет один раз без повторов. Про то, как делиться скиллами, я уже писал. Если нужно длинное сообщение без программы внутри, у бота есть Rich Messages, для них в той же библиотеке telegram-skills свои скиллы.
Нужен свой бот и его токен, секретный ключ от бота. Дальше промпт:
Поставь скилл tg-widgets из библиотеки https://github.com/serejaris/telegram-skills (папка skills/tg-widgets), прочитай его SKILL.md и примеры в examples/.
Сделай виджет для Telegram: аквариум, но с моими цветами. Рисуй на canvas низкого разрешения, как в примере aquarium-pixel.html. После каждой правки меряй размер проверкой из скилла, лимит 4096 байт после zlib.
Отправь виджет в личку с моим ботом. Токен я задам сам в переменной TELEGRAM_BOT_TOKEN, в чат его не проси. Номер чата спроси у меня. Напиши подпись, понятную без виджета. После отправки спроси, как он выглядит у меня на телефоне.
Первый показ делайте на своём телефоне, до любых обещаний аудитории. Там мы потеряли две версии из трёх. Что получилось у вас, покажите в чате вайбкодеров.