What Telegram widgets are
A widget is a small interactive block a bot draws right inside a message: a poll whose bars move as people vote, a promo code that copies on a tap, a countdown to an event. Widgets arrived in Bot API 10.4 in November 2026.
Technically, a widget is one HTML document with inline CSS and JavaScript: at most 32,768 bytes and at most 4,096 bytes after compression. The Telegram app runs it on the person's device in a sandbox with no network access and draws it in the style of the chat.
Code and state
A widget is fixed code plus changeable state.
- The code is set when the widget is sent and never changes. For a new layout you send a new widget; old messages keep the old one.
- The chat state (
chat_data) is tied to one message and seen only in that chat: “you have voted”, “your promo code”. - The shared state (
public_data) is seen wherever the widget is shown: poll results, the number of giveaway participants.
Only the bot writes the state. The widget reads it and redraws, and it can change it in one way only: by asking the bot with a short request of up to 64 bytes, the way a button under a message does. The bot has 15 seconds to answer.
Static and shared widgets
A static widget keeps its code and state in the message itself. A shared widget is one object on Telegram's server that any number of messages show: when the bot changes its shared state, the change reaches all of them. That is how a poll with live results works.
Where widgets work
Telegram is rolling widgets out in steps. According to the documentation, in production they currently work only in the private chat with the bot; groups, inline mode and forwards work only on Telegram's test server so far. A widget cannot be posted to a channel.
| Where | How it gets there | In production |
|---|---|---|
| The private chat with the bot | the bot sends the widget | Yes |
| A group the bot is in | the bot sends the widget | Test server only |
| Any chat except channels | via the bot in inline mode | Test server only |
| A forward to any chat | forwarded by people | Test server only |
So today the main way to spread a widget is a link to the bot: it goes under a channel post or into a chat, the person taps “Start” and gets the widget in the private chat.
How a widget differs from a Mini App
| Mini App | Widget | |
|---|---|---|
| Where | a separate view opened from a button or a link | inside the message bubble, always visible |
| Code | a web page on your server | up to 32 KB of HTML inside the message, fixed once sent |
| Network | the web | none |
| Talking to the bot | your own backend | a short request carried by Telegram |
| Input | everything, keyboard included | taps and gestures; no keyboard, no input fields |
What Widgram takes care of
- The code. Ready-made templates that fit the size limit and pass the widget profile. You only change the settings.
- The server. We take the widget's requests, count votes, hand out promo codes, run giveaways and update the state.
- The check. The emulator shows the widget in a message bubble: themes, width, text size.
Next: how to use the builder and platform limits.
Source: Telegram's official guide to widgets. Telegram sets the rules and may change them; where this page and the guide disagree, the guide is right.