Инженерия · Интерфейсы и 3D

HTML-виджеты Telegram в продакшене

Что потребовалось, чтобы выпустить два живых HTML-виджета в Telegram-боте dtwin: бюджет 4 КБ, состояние 1 КБ, протокол ревизий между ботом и чатом и лимит отрисовки, о котором документация прямо не пишет.

· 4 мин чтения

В Telegram Bot API 10.4 появился новый вид сообщений: небольшая HTML-страница, которую бот отправляет в чат. Там она сама себя рисует, реагирует на нажатия и может обновляться позже без отправки нового сообщения. 10 ноября 2026 года бот dtwin начал отправлять два таких виджета. /osmon — живая карточка неба: солнце или луна движется по дуге, цвет неба меняется со временем суток, идёт обратный отсчёт до следующего намаза. /tasbih — счётчик зикра, который живёт прямо в переписке.

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

  1. ОтправкаБот вызывает sendWidget с HTML, начальным состоянием и текстовой подписью на случай отката.
  2. ЗаписьСообщение сохраняется с типом, номером ревизии и хешем состояния.
  3. ЗапросКогда виджет становится видимым и каждые 20 секунд, пока он активен, он запрашивает у бота свежее состояние.
  4. ДействиеНажатие превращается в короткий запрос, который бот выполняет тем же путём в коде, что и приложение.
  5. Обратная записьЕсли состояние действительно изменилось, бот отвечает виджету и записывает новое состояние в сообщение.
Рисунок 1

Бюджет

Виджет живёт в жёстких рамках. Его HTML должен укладываться в 4 096 байт после сжатия zlib с уровнем 9, состояние, прикреплённое к сообщению, — в 1 024 байта, а внутри виджета нет доступа к сети, ввода текста и фотографий. Всё, что показывает виджет, рисуется из кода и килобайта JSON.

Оба виджета dtwin — это один <canvas> и один скрипт. На момент выпуска карточка неба сжималась до 2 621 байта, а тасбих — до 1 616. Рисование на canvas вместо построения DOM-элементов было не только про размер. Оно ещё и уберегло нас от лимита, о котором речь ниже. 33 бусины тасбиха — радиальные градиенты на одном canvas, а глубина изображается движением по эллипсу и масштабированием. 33 DOM-элемента с прозрачностью — это была бы совсем другая история.

Каждый виджет использует собственную палитру, радиусы и шрифты dtwin. Тасбих, например, тёмно-зелёный, а текущая бусина и кольцо прогресса — золотые. Виджет должен выглядеть частью продукта, а не случайной карточкой, брошенной в чат.

Протокол состояния

Виджет сам ничего загрузить не может. Он может только отправить боту короткую строку, а бот отвечает короткой строкой. В Telegram это называется widget query. Словарь мы сделали крошечным: s запрашивает текущее состояние, p:2 переключает отметку третьего намаза дня, z:17 добавляет в тасбих семнадцать счётов.

Как только состояние течёт в обе стороны, появляются две проблемы. Ответы могут приходить не по порядку, а бот может много раз отвечать неизменившимся состоянием. Обе решаются двумя полями:

  • Ревизия, r. Каждое состояние от бота несёт число, которое только растёт: текущее Unix-время или последняя ревизия плюс один, если время не больше. Виджет принимает входящее состояние, только если его ревизия не старее той, что у него есть, поэтому медленный ответ никогда не откатит карточку назад.
  • Хеш. Бот хранит SHA-256-хеш каждого состояния, посчитанный с обнулённой ревизией. Если хеш нового ответа совпадает с сохранённым, бот отвечает старой ревизией и сообщение не трогает.

editMessageWidgetData бот вызывает только при изменении хеша, поэтому состояние, сохранённое в сообщении (его первым покажет заново открытый чат), остаётся актуальным без правки на каждый опрос. В общих чертах:

var state = data == "s" ? await widget.State(user, ct) : await widget.Apply(user, data, ct);
if (state.Hash() == row.StateHash)
    return (state with { R = row.Revision }).Json();          // nothing changed
state = state with { R = Math.Max(now, row.Revision + 1) };   // monotonic revision
// answer the widget, then editMessageWidgetData and store the new hash

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

Нажатия, переживающие плохую связь

Тасбих нажимают быстро, сотни раз, часто на телефоне с неустойчивым сигналом. Отправлять запрос на каждое нажатие было бы расточительно и хрупко. Вместо этого виджет считает локально:

  • каждое нажатие добавляется к счётчику ожидающих, который сохраняется в localStorage виджета, так что закрытый чат его не теряет;
  • ожидающие счёты отправляются одним запросом z:<n>, не больше 500 за раз, не чаще раза в пять секунд при нажатиях и раза в шесть секунд, пока виджет активен;
  • ожидающее число вычитается только после того, как бот ответил корректным состоянием; при ошибке оно просто остаётся в очереди.

Лёгкая вибрация на каждое нажатие и сигнал успеха с волной на каждом 33-м делают его похожим на настоящие чётки. На сервере собранный счёт попадает в тот же журнал зикра, что и в приложении.

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

Чему научил продакшен

Старым клиентам нужна подпись. Клиент без поддержки виджетов показывает «unsupported media» и подпись, поэтому подпись содержит полный текст карточки. Если падает сам sendWidget, бот отправляет обычное сообщение. Виджеты работают только в личном чате с ботом; в продакшене мы подтвердили и отправку, и обновление.

Есть лимит отрисовки. Если одновременно рисуется больше шестнадцати «тяжёлых» блоков (всё с прозрачностью меньше единицы, CSS-фильтром или размытой тенью, включая псевдоэлементы и transition), Telegram останавливает виджет. Предпросмотр в настольном браузере об этом ничего не скажет. Достаточно анимировать сетку ячеек из прозрачности. Теперь у нас правило: списки и ячейки анимируем только через transform, а эффекты держим на canvas.

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

Коротким ID нужна случайная часть. Более поздние карточки dtwin кладут в состояние восьмисимвольный ID каждой строки, чтобы нажатие могло на неё сослаться. Первая версия брала первые восемь hex-символов UUIDv7, а это метка времени, поэтому строки, созданные примерно в одну минуту, совпадали, и нажатие могло попасть не в ту строку. Исправление вышло в тот же вечер в #329: берутся последние восемь символов, а неоднозначные совпадения отклоняются.

Ограничения

  • Виджеты работают только в личном чате с ботом, не в группах.
  • Таблица, связывающая отправленные сообщения с их состоянием, на момент выпуска не очищалась; старые строки просто копятся, пока не появится задача очистки.
  • Всё, что показывает виджет, должно считаться на сервере и укладываться в 1 024 байта JSON, поэтому длинные списки и историю в карточку не поместить.

Повторите сами

Проверьте, укладывается ли ваш виджет в бюджет Telegram: сожмите HTML через zlib с уровнем 9 и сравните результат с 4 096 байтами.

$ python3 -c "import sys,zlib;print(len(zlib.compress(open(sys.argv[1],'rb').read(),9)))" widget.html
$ git clone https://github.com/TelegramMessenger/widget-sandbox
Репозиторий
Репозиторий закрыт; команды используют только публичные инструменты.
Материалы
wonmortech/research

Источники

  1. core.telegram.org/bots/widgets
  2. core.telegram.org/bots/api
  3. github.com/TelegramMessenger/widget-sandbox
  4. dtwinuz/dtwin #327
  5. dtwinuz/dtwin #329

Похожие материалы

Смотреть ещё