Telegram Widgets: Interactive HTML Inside Bot Messages
Telegram widgets are small interactive HTML blocks that a bot sends inside a message with the sendWidget method, added in Bot API 10.4 on November 9, 2026. A widget is one HTML document of up to 32 KB that the Telegram app runs on the user's device, without any network access, and draws in the chat's own style: an order card that updates its status, a counter, a poll whose bars move as people vote, a promo code copied with one tap.
Where widgets work today: in the production environment a bot can send widgets only to the private chat with a user, and the messages are sent with protected content, so they can't be forwarded. Widgets in groups, in inline mode and in forwards work only on the test server for now.
What a Telegram widget is
- One HTML document. Inline
<style>and<script>, images only asdata:URLs or inline SVG. At most 32768 bytes of UTF-8 and at most 4096 bytes after zlib compression at level 9. A bare fragment without<html>and<body>is fine. - Sandboxed. The JavaScript runs in QuickJS, a small JavaScript engine, not in a WebView. The app checks every change the widget makes against the widget profile and draws only what passes, so the widget looks the same on iOS, Android, macOS, Telegram Desktop and the web.
- Offline.
fetch,XMLHttpRequest,WebSocketand other network APIs throwNetworkDisabledError. External scripts, styles, fonts and images are never loaded, and no library is bundled. - Native. The chat's palette is available as
--tg-theme-*CSS variables, and an unstyled<button>is drawn as the app's own button. - No keyboard. Inputs, selects and text areas are removed. A widget reacts to taps, pointer events, horizontal drags and holds.
Code and state: chat_data and public_data
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, and only the bot writes it. The widget reads it as TelegramWidget.chatData and TelegramWidget.publicData and redraws on the chatDataChanged and publicDataChanged events.
| Property | Chat state (chat_data) | Shared state (public_data) |
|---|---|---|
| Tied to | One original message | The message of a static widget, or a shared widget everywhere it is shown |
| Seen | Only in that chat (one for all members in a group) | Wherever the widget is shown |
| In a forward | Never | A copy (static widget) or the live shared state (shared widget) |
| Size | Up to 1024 bytes of text | Up to 1024 bytes of text |
| Changed with | editMessageWidgetData | editMessageWidgetData or editSharedWidgetData |
| Examples | A game in progress, an order status | Poll results, a price |
Both are plain text that the server does not interpret, usually JSON. In the widget, an absent or cleared state is null.
Where widgets live: production vs test server
| Place | How it gets there | Requests (with allow_queries) | Production |
|---|---|---|---|
| Private chat with the bot | sendWidget, sendSharedWidget | On a tap and in the background | Yes |
| Basic group or supergroup | sendWidget | On a tap only | Test server only |
| Any chat except channels, via the bot | Inline mode (InputWidgetMessageContent, InputSharedWidgetMessageContent) | On a tap only | Test server only |
| A forward, channels included | Forwarded by users | On a tap, shared widgets only | Test server only |
Bots can't post widgets in channels. Apps that don't support widgets show the message as unsupported media with its caption. Widget messages can't be copied with copyMessage or copyMessages, and in groups the can_send_other_messages permission also covers widgets.
Telegram widgets vs Mini Apps
| Property | Mini App | Widget |
|---|---|---|
| Where | A WebView opened from a button, the menu or a link | Inside the message bubble, always visible in the chat |
| Code | A web page on your server | Up to 32 KB of HTML inside the message, fixed once sent |
| Engine | The platform's WebView | QuickJS sandbox, drawn by the Telegram app |
| Network | The web | None |
| Talking to the bot | Your backend, with signed initData | TelegramWidget.request() → widget_query update |
| Input | Everything, keyboard included | Taps and pointer events, no keyboard |
Where the APIs overlap, TelegramWidget reuses the names of Telegram.WebApp (themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready). For anything bigger than a widget, open your bot or Mini App with openTelegramLink. If you are building a Mini App instead, see how to test a Telegram Mini App.
Send your first widget with sendWidget
- Create a bot and copy its token (how to create a Telegram bot, where to find the bot token).
- Send
/startto the bot so it can write to you, and take your chat id fromgetUpdates. - Call sendWidget. The
htmlparameter is a string, so send the request as JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>Your promo code</h3><p>Tap the button to copy it.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "Your promo code: PROMO10"
}'
The same in Python with requests or in JavaScript with fetch:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Your promo code</h3>
<p>Tap the button to copy it.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "Your promo code: PROMO10",
}, timeout=10)
print(r.json()) # result: the sent Message with its "widget" fieldconst API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Your promo code</h3>
<p>Tap the button to copy it.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;
const r = await fetch(`${API}/sendWidget`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: 123456789,
html,
caption: "Your promo code: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: the sent Message with its "widget" fieldThis widget has no CSS at all and still looks like a normal message with a native button. TelegramWidget exists without any script tag, and copyText works because it is called in the handler of a tap. You can also paste the HTML into the sendWidget form of the Bot API Tester and send it with your own token.
Other sendWidget parameters: width and height (size anchors in logical pixels), chat_data and public_data (initial state), allow_queries, is_shared, plus the usual caption, reply_markup, reply_parameters, message_thread_id and protect_content.
How a widget talks to the bot
A request works like a callback button inside the widget:
- The bot sends the widget with
allow_queries: true. - On a tap, the widget calls
TelegramWidget.request("like")with 1–64 bytes of data. - The bot receives a
widget_queryupdate withid,from,chat,message_idanddata(from a forward of a shared widget: ashared_widget_query). If you passallowed_updates, include both types. - The bot calls answerWidgetQuery within 15 seconds, optionally with
dataof up to 1024 bytes that only the asking widget receives. - To change what everyone sees, the bot calls editMessageWidgetData (or
editSharedWidgetData); the widget getschatDataChanged/publicDataChanged.
The answer itself never changes the state. Requests are limited to 5 per 5 seconds per user and bot; a missed answer ends as TIMEOUT in the widget. Full working code is in Telegram widget examples.
Static and shared widgets
Without is_shared a widget is static: code and state live in the message, and a forward gets a frozen copy. With is_shared, the first send creates a shared widget: one object with an identifier (widget.id in the returned message) that any number of messages can show. Send it again with sendSharedWidget and change its shared state for all of them at once with editSharedWidgetData, at most once per second. A widget already on screen receives new shared state only after it calls TelegramWidget.watchPublicData(); the app then polls at the widget's refresh period (30 seconds by default, 5–3600 via cache_time).
Telegram widget limits at a glance
| What | Limit |
|---|---|
| HTML | 32768 bytes; 4096 bytes after zlib level 9 |
chat_data, public_data | 1024 bytes each |
| Request data / answer data | 1–64 bytes / up to 1024 bytes |
| Time to answer a query | 15 seconds |
| Requests | 5 per 5 seconds per user and bot |
| Bubble size | 200 px to the bubble's maximum wide, 50–600 px tall; the rest is clipped |
| Shared widget edits | 1 per second |
| Memory / DOM nodes | 8 MB / 2000 nodes |
The complete table, with CPU quotas, timers and storage, is in the TelegramWidget API reference.
Design tips
- Always send a caption. It is what the chat list, notifications, search and apps without widget support show.
- Use the theme. Build colors on
--tg-theme-*variables and test both light and dark chat themes;prefers-color-schemefollows the chat theme, not the system. - Draw the first state at once from
chatData/publicData; there is nothing to load. - Keep it small. Count the compressed size the way the server does:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - No secrets. Treat the code and the shared state as public; in a group every member sees the chat state.
- Lay out for the width with
%, flex or grid.vhis not supported and nothing scrolls inside a widget. - Show every outcome of a request: "Sending…", the answer and each error code.
Not to be confused with website widgets
"Telegram widget" also refers to the older widgets for websites: the Telegram Login Widget, post embeds and the share button. Those are scripts you put on your own site. Bot API 10.4 widgets are something else: HTML that a bot sends into a chat. For login, post embeds and sharing on your site, see our guide to Telegram website widgets. The official widget documentation lives at core.telegram.org/bots/widgets.
Next steps
- Telegram widget examples: an order card, a counter with requests and a shared live poll, with Python bot code.
- TelegramWidget JavaScript API: properties, methods, events, error codes, CSS variables and limits.
- What's new in Bot API 10.x: everything else that shipped with 10.4.
Frequently asked questions
What are Telegram widgets?
Small interactive blocks drawn inside a bot's message, added in Bot API 10.4 (November 9, 2026). A widget is one self-contained HTML document with inline CSS and JavaScript that the Telegram app runs on the user's device in a sandbox without network access.
Do Telegram widgets work in groups?
Not in production yet. Currently a bot can send widgets in production only to the private chat with a user, and they can't be forwarded. Groups, inline mode and forwards already work on the test server.
How do I send a widget from a bot?
Call sendWidget with chat_id and html (a string, 1–32768 bytes, at most 4096 bytes after zlib level 9 compression), plus an optional caption, chat_data, public_data and allow_queries. The method returns the sent Message with its widget field.
Can a Telegram widget make HTTP requests?
No. fetch, XMLHttpRequest, WebSocket and every other network API throw NetworkDisabledError. The only way out is TelegramWidget.request(), which sends 1–64 bytes to your bot as a widget_query update.
What is the difference between a widget and a Mini App?
A Mini App is a web page you host, opened in a WebView from a button or link, with full network access. A widget lives inside the message bubble, is at most 32 KB of HTML fixed at sending, has no network and talks only to its bot through requests.
Can I change a widget's HTML after sending?
No. The code is fixed once sent; only the state changes. Update chat_data or public_data with editMessageWidgetData or editSharedWidgetData, or send a new widget for a new layout. The caption can be edited with editMessageCaption.
Related guides
How to Create a Telegram Bot: Step by Step with BotFather and Python
How to create a Telegram bot step by step: register it with @BotFather, get the token, test it with getMe and send a first message with curl or Python.
Telegram Bot API 10.0–10.5: Bot Settings, Widgets, Rich Messages, Ephemeral Messages, Guest Mode and More
What's new in Telegram Bot API 10.0–10.5: setMySettings and BotFullInfo, HTML widgets, rich and ephemeral messages, guest mode, with JSON examples.
Telegram Bot API Limits: Rate Limits, 429 Errors, File Sizes and Message Length
Telegram Bot API rate limits explained: 30 msg/s, 1 msg/s per chat, 20/min in groups, handling 429 retry_after, plus file size and message length limits.
How to Send a Message with the Telegram Bot API (sendMessage)
Telegram Bot API send message guide: sendMessage with curl, Python and JavaScript, HTML and MarkdownV2 formatting, inline buttons and error fixes.
Telegram Bot Token: How to Get It, Find It Again, Check It and Keep It Safe
Telegram bot token guide: get one from @BotFather, find the token of an existing bot, check it with getMe, revoke a leaked token and store it safely.
How to Set Up a Telegram Bot Webhook: setWebhook, Secret Token and Troubleshooting
Set up a Telegram bot webhook: setWebhook URL requirements, secret_token header check, getWebhookInfo debugging, deleteWebhook and fixes for n8n.
How to Get a Telegram Chat ID for a User, Group, Channel or Topic
How to get a Telegram chat ID for a user, group, supergroup, channel or forum topic with getUpdates, plus fixes for an empty result and 409 Conflict.
Telegram Test Server: How to Test a Bot in the Telegram Test Environment
Use the Telegram test server for bots: log in to the test environment, create a test bot, call the Bot API via /test/ and switch our tester to TEST.
Telegram Widgets for Your Website: Login Widget, Post Embed, Discussion and Share Button
Add Telegram to your website: the new Telegram Login (OIDC), the legacy Login Widget with hash check code, post embeds, comments and a share button.
TelegramWidget JavaScript API: Reference, Events, Error Codes and Limits
TelegramWidget JavaScript API reference: properties, request(), events, error codes, CSS variables, widget_query and answerWidgetQuery, plus every limit.
Telegram Widget Examples: Complete HTML and Python Bot Code
Working Telegram widget examples with full code: a static order card, a counter with widget_query requests, a shared live poll and a local preview stub.
How to Test a Telegram Mini App: From Browser Mock to Real Telegram
Test a Telegram Mini App step by step: browser mock mode, localhost via HTTPS tunnel, test environment, DevTools per platform, initData validation.