From 2e489ce63ded2fe66c083fa28ddd90c28098f52a Mon Sep 17 00:00:00 2001 From: roon9e <44918054+roon9e@users.noreply.github.com> Date: Fri, 6 Nov 2026 19:34:08 +0300 Subject: [PATCH] docs(widgets): record the Layer 233 widget surface Documents docs/bot-widgets.md: media (message + inline), public/chat data, the durable updateMessageWidgetData event, the bot query round trip, transcription files, and the deliberate limits (process-local query registry, unmodelled channel forum sidebar, no TON widget signing). --- docs/bot-widgets.md | 64 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/bot-widgets.md diff --git a/docs/bot-widgets.md b/docs/bot-widgets.md new file mode 100644 index 00000000..33215a37 --- /dev/null +++ b/docs/bot-widgets.md @@ -0,0 +1,64 @@ +# Bot web widgets (Layer 233) + +`gramsrv` implements the Layer 233 bot web-widget surface. This document records +what the server does and the deliberate limits. + +## Media + +- `inputMediaWidget` becomes `messageMediaWidget`. The markup, box size and + `allow_queries` flag are stored on the message media snapshot. +- When `shared_widget` is set, the widget definition (HTML, payload, size, + `allow_queries`, public data) is also persisted in the `bot_widgets` table and + gets a server-assigned `widget_id`. +- `inputMediaWidgetID` resolves that definition by id and attaches it to the + message as an `is_copy` widget. `chat_data` from the input is kept. +- The widget is accepted through `messages.sendMedia` / `sendMultiMedia` / + `uploadMedia`, and through inline bot results: `inputBotInlineMessageWidget` / + `inputBotInlineMessageWidgetID` project back to `botInlineMessageWidget`. It is + not accepted on ephemeral or story media. + +## Public / chat data + +- `messages.getWidgetPublicData(peer, msg_id, hash)` returns + `messages.widgetPublicData{hash, data, period}` or + `messages.widgetPublicDataNotModified{period}` when the client already has the + current `hash`. The effective data is the shared widget's data (when the + message references a `widget_id`) over the per-message snapshot. +- `messages.editMessageWidgetData(peer, id, public_data?, chat_data?)` mutates + the message media snapshot through the normal message-edit path (the edit update + refreshes the client's message) **and** records the durable pts-bearing + `updateMessageWidgetData` event (difference, offline replay and proactive + delivery). +- `messages.editInlineBotMessageWidgetData(id, public_data?, chat_data?)` does + the same for inline-bot messages owned by the calling bot. +- `messages.editWidgetData(widget_id, public_data, cache_time?)` replaces the + shared widget's public data; only the widget's owner bot may call it. + +## Queries + +- `messages.getBotWidgetQueryAnswer(peer, msg_id, query_type, data)` registers a + pending query, pushes `updateBotWidgetQuery` to the widget's bot, and waits up + to 25 s for the answer. +- `messages.setBotWidgetQueryAnswer(query_id, result?)` unblocks the waiter. + Only the owning bot may resolve a query id; anything else is + `QUERY_ID_INVALID`. A missing answer ends in `BOT_RESPONSE_TIMEOUT`. + +## Transcription files + +- `messages.transcribeAudioFile(file)` assembles the upload into a document and + runs it through the existing ASR service (`TELESRV_ASR_URL`); it caches by + document id and the client re-calls until `pending` is false. +- `messages.getTranscriptionLangs` returns an empty list: the ASR backend exposes + no fixed language set. + +## Deliberate limits + +- The bot query registry is process-local (like the pre-checkout registry); a + multi-node deployment must be single-node for the bot's answer to land, or the + registry must gain a shared store like `BotCallbackRegistryStore`. +- `channels.toggleForum` models only the list and tabs layouts: enabling a forum + with `sidebar=true` fails closed (the author's Layer 233 decision is unchanged), + and `channel.forum_sidebar` is never emitted. +- `updateBotWidgetQuery.wallet_card` is not populated; TON widget signing is not + implemented (`wallet.tonConnect*` still refuses). +