Skip to content
Widgram

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

WhatLimit
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, select and textarea are removed with their content. The only control is button. 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, WebSocket and the other network calls throw. The only way out is a request to the bot.
  • Part of CSS. vh units, scrolling (overflow: auto and scroll become hidden), position: sticky, 3D transforms, text-shadow, clip-path, :has(), @font-face, @import, nesting, modern color functions such as oklch().
  • Named fonts. Only generic families work: system-ui, sans-serif, serif, monospace.
  • Dialogs and the clipboard. alert, confirm and prompt show nothing, and navigator.clipboard is not available. Text is copied with TelegramWidget.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 @keyframes animations.
  • The chat theme colors as the CSS variables --tg-theme-*; prefers-color-scheme and prefers-reduced-motion.
  • ES2023 JavaScript, timers, requestAnimationFrame, localStorage within its limit.
  • The TelegramWidget object: 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.