Platform limits
A widget lives within tight bounds: a small size, a sandbox with no network, a limited set of HTML, CSS and JavaScript. Whatever falls outside them the Telegram app removes silently: the widget does not fail, but it looks and works differently from what was intended. Widgram templates already fit these bounds; this page is for those who write a widget themselves or want to understand why a template is built the way it is.
Limits
| What | Limit |
|---|---|
| The widget's code | 32,768 bytes of UTF-8 |
| The code after compression | 4,096 bytes (zlib, level 9) |
| The chat state and the shared state | 1,024 bytes each |
| A request to the bot | 1 to 64 bytes |
| The bot's answer | up to 1,024 bytes |
| Time to answer | 15 seconds |
| Requests from one person | 5 per 5 seconds |
| Updates of a shared widget | 1 per second |
| Refresh period of a shared widget | 30 seconds by default, from 5 to 3,600 |
| The widget's size | 200 px to the bubble's width wide, 50–600 px tall |
| Storage on the device | 4,096 bytes per area |
| Text to copy | up to 256 characters, on a tap |
| A link's address | up to 256 characters |
| Document nodes | 2,000 |
| CSS rules | 400 rules and 32 @keyframes animations |
| Heavy elements (blurred shadow, filter, opacity) | 16 at once |
| Timers | 64 at once |
| CPU time | 300 ms of script per second |
| Memory | 8 MB |
The compressed size is the main limit: the markup, the styles and all the logic must fit in 4,096 bytes. The code check counts it the way Telegram's guide describes: zlib, level 9.
What the app removes
- Input fields.
input,selectandtextareaare removed with their content. The only control isbutton. There is no keyboard. - Anything external. Scripts, styles, fonts and images by URL are never loaded. Images are
data:PNG, JPEG, GIF and WebP only, or inline SVG. - The network.
fetch,XMLHttpRequest,WebSocketand the other network calls throw. The only way out is a request to the bot. - Part of CSS.
vhunits, scrolling (overflow: autoandscrollbecomehidden),position: sticky, 3D transforms,text-shadow,clip-path,:has(),@font-face,@import, nesting, modern color functions such asoklch(). - Named fonts. Only generic families work:
system-ui,sans-serif,serif,monospace. - Dialogs and the clipboard.
alert,confirmandpromptshow nothing, andnavigator.clipboardis not available. Text is copied withTelegramWidget.copyText, on a tap. - Keyboard, wheel and touch events. Use pointer events instead of touch events.
What works
- Ordinary markup: blocks, headings, lists, tables,
details,button,canvas, inline SVG. - Flexbox and grid, gradients, rounded corners, shadows, transitions and
@keyframesanimations. - The chat theme colors as the CSS variables
--tg-theme-*;prefers-color-schemeandprefers-reduced-motion. - ES2023 JavaScript, timers,
requestAnimationFrame,localStoragewithin its limit. - The
TelegramWidgetobject: the state, a request to the bot, the viewer, links, copying text.
Rules we follow in the templates
- Theme colors and relative sizes only: the widget looks like a message in the light and the dark theme.
- No taller than 560 px at a width of 320 px: the app clips whatever is above 600 px.
- Nothing tappable in the bottom right corner: the message time is there.
- The author's data reaches the page as text only, and secrets (correct answers, promo codes, wheel weights) stay on the server: a widget's code is public.
- The first frame is drawn at once from the state: the app may destroy and recreate a widget at any moment.
Source: Telegram's official guide to widgets, widget profile 1. Telegram sets the rules and may change them; where this page and the guide disagree, the guide is right.