Telegram HTML widgets

Bot API 10.4, released on 9 November 2026, lets a bot put a small HTML app inside a message. This guide covers what a widget is, what works in production today, the limits, and a minimal example of the whole request loop.

What works today, and what does not

Widgets are rolling out in steps. Telegram's availability table splits the feature between production and the test server:

• Private chats only. In production a bot can send a widget only to a private chat with a user, and the message is protected automatically, so it cannot be forwarded (sendWidget).
• No copies. copyMessage and copyMessages refuse widget messages (changelog).
• No channels. A bot cannot post a widget in a channel, directly or through inline mode. On the test server users can forward one there.
• Older apps see the caption. An app without widget support shows the message as unsupported media with its caption, so always send a caption (Where widgets live).
• The test server is separate. It needs its own user account and its own bot, and requests go to https://api.telegram.org/bot<token>/test/sendWidget (how to log in).

Pavel Durov's announcement of 10 November says "Any Telegram message can now become an app", with payments and viral mechanics built in. That describes the whole design. Production today has the first step: a widget in the one-to-one chat between a bot and a user who started it, with requests and wallet payments. The sharing side (forwards, groups, inline mode) runs on the test server, and Telegram's documentation gives no date for it.

What Bot API 10.4 added

Telegram published Bot API 10.4 on 9 November 2026 (changelog, @BotNews post). The widget part is five methods, two update types and a few objects:

The same release added the TON wallet objects that widget payments use, such as TonWalletCard. The widget's own JavaScript object, TelegramWidget, is documented in the widgets guide.

How a widget talks to its bot

A widget is fixed code plus changeable state. The HTML is set when the widget is sent and never changes: no method replaces it. What changes is the state, a short text that only the bot writes (The widget's state):

• Chat state, chat_data: up to 1,024 bytes tied to one message and seen only in that chat. The widget reads it as TelegramWidget.chatData.
• Shared state, public_data: up to 1,024 bytes seen wherever the widget is shown. The widget reads it as TelegramWidget.publicData.

The widget cannot change its own state and has no network access. Its one way out is a request to the bot, which works like a callback button inside the widget (Requests to the bot):

1. The bot sends the widget with allow_queries set to true. Without it, every request from that widget is refused.
2. On a tap the widget calls TelegramWidget.request(data) with 1 to 64 bytes. The call has to be made inside the tap's handler, synchronously: one tap unlocks one call.
3. The bot receives a widget_query update with the query id, the user in from, the chat and message_id, and the data. The query does not carry the widget's state, so the bot keeps the real state on its side and treats data as untrusted input.
4. To change what the widget shows, the bot calls editMessageWidgetData. An open widget gets the chatDataChanged event and redraws. Edits are silent: no "edited" mark and no notification.
5. The bot calls answerWidgetQuery for every query within 15 seconds, also when something failed. The optional data, up to 1,024 bytes, reaches only the widget that asked. An answer never changes the state and shows nothing in the app, and it may come before or after the edit.

In the private chat with the bot a widget may also ask without a tap while it is on screen: once when it appears, then at most once every 5 seconds. Everywhere else a request needs a tap.

A minimal example

Two files: a widget that counts glasses of water, and a bot that keeps the count. They follow Telegram's documentation as of 11 November 2026 and use plain HTTPS calls, so they do not depend on a bot library having shipped Bot API 10.4.

1. Send a static widget with curl

The quickest check that your bot and your app handle widgets. You need a bot token and the chat ID of a user who has started the bot:

curl -s "https://api.telegram.org/bot$BOT_TOKEN/sendWidget" \
  -d chat_id=123456789 \
  --data-urlencode "html=<h3>Booking confirmed</h3><p>Table for two, Friday at 20:00</p>" \
  --data-urlencode "caption=Booking confirmed"

No CSS and no script: Telegram's default styles make a bare widget look like an ordinary message.

2. The widget: widget.html

<style>
.n{font-size:2.4em;font-weight:700;line-height:1.2}
.hint{color:var(--tg-theme-hint-color);font-size:.87em}
button{display:block;width:100%;margin:8px 0 2px}
</style>
<div>Glasses of water today</div>
<div class="n" id="n">0</div>
<button id="add">+1 glass</button>
<div class="hint" id="msg">&nbsp;</div>
<script>
const W = window.TelegramWidget;
const $ = (id) => document.getElementById(id);

function draw(json) {
  let state = null;
  try { state = JSON.parse(json); } catch (e) {}
  $('n').textContent = (state && state.n) || 0;
}
function say(text) { $('msg').textContent = text || '\u00a0'; }

$('add').addEventListener('click', () => {
  if (!W) return;
  say('Sending...');
  W.request('add').then(
    (answer) => { say(''); if (answer.result) draw(answer.result); },
    (error) => say('Not sent: ' + error.code)
  );
});

if (W) {
  W.onEvent('chatDataChanged', () => draw(W.chatData));
  draw(W.chatData);
}
</script>

This widget is 940 bytes of HTML and 563 bytes after zlib at level 9, against limits of 32,768 and 4,096.

3. The bot: bot.py

# bot.py - Python 3.8+, standard library only
import json
import os
import urllib.error
import urllib.request

API = "https://api.telegram.org/bot" + os.environ["BOT_TOKEN"] + "/"
WIDGET = open("widget.html", encoding="utf-8").read()
counts = {}  # (chat_id, message_id) -> glasses; a real bot uses a database


def call(method, **params):
    request = urllib.request.Request(
        API + method, json.dumps(params).encode(),
        {"Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(request, timeout=70) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:  # Telegram's errors are JSON too
        result = json.load(error)
        print(method, "failed:", result.get("description"))
        return result


offset = 0
while True:
    reply = call("getUpdates", offset=offset, timeout=50,
                 allowed_updates=["message", "widget_query"])
    if not reply.get("ok"):
        raise SystemExit(1)
    for update in reply["result"]:
        offset = update["update_id"] + 1
        message = update.get("message")
        query = update.get("widget_query")
        if message and (message.get("text") or "").startswith("/start"):
            call("sendWidget", chat_id=message["chat"]["id"], html=WIDGET,
                 chat_data=json.dumps({"n": 0}), allow_queries=True,
                 caption="Water tracker")
        elif query:
            key = (query["chat"]["id"], query["message_id"])
            n = counts.get(key, 0)
            if query["data"] == "add":
                edit = call("editMessageWidgetData", chat_id=key[0],
                            message_id=key[1],
                            chat_data=json.dumps({"n": n + 1}))
                if edit.get("ok"):  # commit only after the edit went through
                    n = counts[key] = n + 1
            # answer every query within 15 seconds, also when nothing changed
            call("answerWidgetQuery", widget_query_id=query["id"],
                 data=json.dumps({"n": n}))

The count lives in memory, so a restart forgets it. A real bot keeps it in a database, keyed by chat and message.

4. Run it

read -rs BOT_TOKEN && export BOT_TOKEN   # paste the token, press Enter
python3 bot.py

Then open the chat with your bot in Telegram and send /start. Each tap on the button goes through the five steps above. If the bot has a webhook set, remove it first with deleteWebhook: getUpdates does not work while a webhook is set.

Limits

The numbers that decide what fits, from the limits table of Telegram's guide and the Bot API reference:

The compressed size is usually the limit you hit first. Telegram's guide gives this command and says Python's zlib counts exactly as the server does, while gzip -9 counts about 12 bytes more and other zlib builds can be a few dozen bytes off:

python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html

Errors you will meet

For the rest of the Bot API's errors, see the error code reference.

What a widget can and cannot do

Telegram calls the contract between widgets and its apps the widget profile. Every app removes what is outside it before drawing, without an error, so a missing feature is a bug you will not see (What widgets support):

• One HTML document. Inline <style> and <script>, images only as data: URLs or inline SVG. External scripts, stylesheets, fonts and images are never loaded.
• JavaScript runs, in a sandbox. Scripts run in QuickJS, a small JavaScript engine, never in a browser or a WebView. ES2023, Promises, timers, requestAnimationFrame, the DOM, canvas 2D and localStorage are in.
• No network. fetch, XMLHttpRequest, WebSocket and every other network API throw NetworkDisabledError. Data comes in through the state and the bot's answers.
• No typing. Inputs, selects and text areas are removed, and <button> is the only form control. A widget gets taps, pointer events, horizontal drags and holds, and no keyboard.
• No scrolling inside. Vertical drags always scroll the chat, and content taller than the bubble is clipped.
• The chat's colors. The palette arrives as CSS variables such as --tg-theme-text-color and --tg-theme-button-color, and a <button> you do not style is drawn as the app's own button.
• No media, no frames. audio, video and iframe are out, and so are web fonts: system font families only.
• No accessibility semantics yet. aria-* attributes are kept but do nothing in this version, so what matters goes in the caption too.
• The bot learns only from requests. It sees who tapped and the data the widget sent. A widget that may not send requests does not know who is looking at it (Privacy).

To try a layout, a desktop browser 320 to 430 px wide gives a first look, with a stand-in for TelegramWidget; a browser draws everything and enforces none of the limits. Telegram also publishes the sandbox its apps use, widget-sandbox on GitHub, with a dev app that loads an HTML file into a bubble-sized frame.

Shared widgets

Pass is_shared to sendWidget and Telegram creates a shared widget: one object on the server, like a poll, that any number of messages can show. The returned message carries its identifier in widget.id (Static and shared widgets).

• sendSharedWidget sends the same widget again by widget_id, with that message's own chat_data and caption.
• editSharedWidgetData changes the shared state once, for every message that shows the widget. A shared widget takes at most one edit per second.
• An open widget picks up a new shared state only if it called TelegramWidget.watchPublicData(). The app then polls at the widget's refresh period: 30 seconds by default, 5 to 3,600 seconds through cache_time. Otherwise the new state arrives when the message is opened or scrolled into view.
• The code, the size and the request flag of a shared widget never change. A new layout means a new widget.

POST https://api.telegram.org/bot<token>/sendWidget
{"chat_id": 111111111, "html": "...", "public_data": "{\"left\":12}",
 "is_shared": true, "caption": "Seats left: 12"}

POST https://api.telegram.org/bot<token>/sendSharedWidget
{"chat_id": 222222222, "widget_id": "<widget.id from the first call>",
 "caption": "Seats left"}

POST https://api.telegram.org/bot<token>/editSharedWidgetData
{"widget_id": "<widget.id>", "public_data": "{\"left\":11}", "cache_time": 10}

The production note on sendSharedWidget is the same as on sendWidget, private chats only. So one case is already covered: the same live widget in many private chats, updated with one call. The other half of the design depends on forwards: a forwarded shared widget keeps following the shared state and sends its taps to the bot as shared_widget_query updates. Forwards run on the test server only for now.

Payments: the TON wallet

A widget can ask the user to pay or to sign with the wallet built into Telegram. The formats are TON Connect's, without a connection, a manifest or a bridge: the bot that sent the message is the one asking, and the app's own wallet window says so (Payments with the wallet). Telegram's availability table lists the wallet as working in production, in the private chat with the bot.

1. The widget checks TelegramWidget.wallet. It is null where the user has no wallet in this app, for example an older app or a country where the wallet is unavailable.
2. On a tap it calls request(data, { wallet: true }). The bot's widget_query then has a type of data with the user's wallet_card: its address and balance.
3. The bot answers with a transaction in TON Connect's sendTransaction format: recipients, and amounts in nanotons.
4. The widget passes it to wallet.sendTransaction(transaction, data) within 10 seconds of the answer. The app shows the bot, the amounts and the destinations, and the user confirms.
5. The bot gets a second query with a type of sent_transaction and the message hash. Telegram's guide says to check the transaction on the chain, not by the hash alone.

// in the widget, inside the handler of a tap
TelegramWidget.request('pay:42', { wallet: true })
  .then((answer) => TelegramWidget.wallet.sendTransaction(
    JSON.parse(answer.result), 'paid:42'))
  .then((answer) => show(answer.result), (error) => show(error.code));

wallet.signData asks for a signature the same way, and the bot receives a sign_data query. A request the user declines rejects with REJECTED. After a TIMEOUT the payment may still have gone out, so the widget should ask the bot about the order instead of paying again.

Stars are not part of this. The widget documentation describes the TON wallet flow only, and does not mention Telegram Stars or invoices. Telegram's Bot Developer Terms, section 6.2, still require digital goods and services to be sold for Stars. The documents do not say how the two fit together, so read the terms before you price digital goods in TON.

Widgets, Mini Apps or an inline keyboard?

Telegram's guide is direct about it: a widget is not a small Mini App. A Mini App is a web page you host, opened on demand. A widget is part of the message, visible as the chat scrolls, with no network access (Widgets and Mini Apps). An inline keyboard is the older and simpler tool: buttons under a message.

• An inline keyboard when a few buttons under a message do the job. It works wherever your bot can post, and you can build one in the inline keyboard builder.
• A widget when the message itself should show live state that the user can glance at and tap: an order's progress, a counter, a poll, a small game. The price is 4 KB compressed, no typing, no network and, for now, the private chat only.
• A Mini App for anything bigger: forms, typing, long lists, network calls, your own backend. A widget can open one with openTelegramLink.

What Telegram has not documented

• App versions. The guide names the platforms (iOS, Android, macOS, Telegram Desktop and the web) and says unsupported apps show the caption. It lists no minimum versions. On 11 November 2026 our test widget drew in the Telegram desktop app and not in Telegram Web A.
• Dates. "Rolling out in steps" is all it says about groups, inline mode and forwards reaching production.
• Stars. Nothing on Telegram Stars or invoices inside a widget, and nothing on how wallet payments relate to section 6.2 of the Bot Developer Terms.
• Costs. No fee specific to widgets is mentioned. sendWidget has the same optional paid broadcast as the other send methods, 0.1 Stars per message above the free sending limits.

Sources

Everything on this page comes from these documents, read on 11 November 2026:

• Bot API changelog, Bot API 10.4, 9 November 2026
• Bot API reference: sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData, editSharedWidgetData, Widget, WidgetQuery, SharedWidgetQuery, WidgetQueryType
• Telegram Widgets, Telegram's guide to designing and implementing widgets
• the @BotNews post, 9 November 2026, and Pavel Durov's post, 10 November 2026
• TelegramMessenger/widget-sandbox, the sandbox Telegram's apps run widgets in
• Telegram Bot Platform Developer Terms of Service, section 6.2

tgkit is an independent project and is not affiliated with Telegram. If the rollout changes, the availability table at the top of this page is the first thing that goes out of date.

Telegram widget FAQ