# Telegram Widgets Bots can send **widgets**: small interactive blocks drawn right inside a message. A widget is one self-contained HTML document with inline CSS and JavaScript, at most 32 KB of HTML and 4 KB after compression. Telegram apps run it on the user's device in a sandbox with **no network access at all**, draw it in the style of the chat, and keep it running while it is on screen: a poll whose bars move as people vote, a price ticker, a board game for two in a group, a promo code that copies on a tap. A widget is **fixed code plus changeable state**. The code, its HTML, is set when the widget is sent and never changes. What changes is the widget's state, and only the bot writes it: the **chat state**, tied to one message and seen only in that chat, and the **shared state**, seen wherever the widget is shown. The widget reads its state and redraws when it changes. It cannot change the state itself, but it can ask the bot with small requests, the way a callback button does. Widgets live in the private chat with the bot, in groups, in messages sent via the bot in inline mode, and in forwards to any chat. Currently, in the production environment, widgets work only in the private chat with the bot. The rest works on the [test server](#availability). A widget can also be a **shared widget**: one widget on the server, like a poll, that any number of messages show, with one shared state for all of them. This page is a guide to designing and implementing widgets, followed by the reference of the widget's JavaScript object `TelegramWidget`. The Bot API methods and types for widgets are in the [Bot API reference](/bots/api.md). --- ### Introducing widgets #### Code and state A widget is fixed code plus changeable state. - **The code** (the HTML with its CSS and JavaScript) is set when the widget is sent and never changes, in a message or in a shared widget. No method replaces it. For a new layout, send a new widget, and old messages keep the old one. As with any media, the caption can be edited. - **The state** is what changes, and only the bot writes it. There are two kinds: - **chat state** (`chat_data`): tied to one message, seen only in that chat (shared by all members in a group), never carried by a forward. A game in progress, whose turn it is. - **shared state** (`public_data`): seen wherever the widget is shown. A static widget keeps it in the message, and a forward gets a copy as of the moment of forwarding. A [shared widget](#static-and-shared-widgets) (one object with an identifier, like a poll) has one shared state for all its messages and forwards. Poll results, a price. - **The widget** reads its state, learns about changes through the `chatDataChanged` and `publicDataChanged` events, and cannot change its state itself: it can only ask the bot, with a [request](#requests-to-the-bot). Details: [The widget's state](#the-widgets-state). #### What a widget is - **One HTML document.** Inline ` ``` Set `chatData`, `publicData`, `viewer` and `isForward` to the cases you want to see, and answer `request` the way your bot would. #### Testing in Telegram Every place a message can go gives the widget different rights, so test each one with your bot. On the [test server](/bots/webapps.md#using-bots-in-the-test-environment) every bot has all of them. In the production environment a bot currently has only the private chat ([Availability](#availability)): - **The private chat with the bot:** the chat state, background requests (one when the widget appears, then one per 5 seconds), a request made in the script's first lines. - **A group with two accounts:** one chat state for everyone, `viewer` different in each account, requests on a tap only. - **Inline mode:** the [preview](#previews) in the list of results, the message sent via the bot, its requests with `inline_message_id`. - **Forwards:** a static widget's forward is a snapshot that cannot ask. A shared widget's forward follows the shared state and, if sent with `allow_queries`, asks through `shared_widget_query`. - **The look:** both color schemes, an outgoing bubble (a widget sent via the bot), the largest text size, a narrow phone and a desktop app with a mouse, a message without a caption and with one above and below ([the time in the corner](#the-time-in-the-corner)), a right-to-left interface language. - **The speed:** an older phone. The [limits](#limits) are the same everywhere, but a widget that is slow on an old phone stays slow there. The test server also keeps experiments away from real users. --- ### Writing widgets with an LLM Models write widgets well when they are told the rules. Put this block into the model's system prompt: ```text You write Telegram widgets. A widget is one self-contained HTML document (or a fragment) with inline

``` Then give the model your bot's side of the contract: - **The protocol**: the JSON shapes of the chat state, the shared state and the answers, the request `data` values the bot understands, and how you send the widget (static or `is_shared`, with or without `allow_queries`). - **Live shared state**: if the widget shows a shared widget's shared state that the bot keeps changing (counts, prices, scores), it calls `TelegramWidget.watchPublicData()` and keeps the newest revision. Otherwise it gets a new shared state only with the message. - **The places**: what the widget should show in a forward (no chat state, `chatType` `null`, maybe no requests), in a group (one chat state for everyone, drawn per `viewer.id`) and in a preview (`isPreview`: no taps). - **The checks**: have the model count the size as in [Counting the size](#counting-the-size), compare its widget with the out list in the block, and test the result in Telegram before you send it to users.