Skip to content

serejaris/telegram-skills / skills/tg-widgets

tg-widgets

Verified

Use when building or sending a Telegram message widget (HTML bubble, HTMLBubbles, `sendWidget`, `messageMediaWidget`, Bot API 10.4): an interactive HTML, CSS and JS program inside a chat bubble, such as a game, poll, calculator or live ticker. Teaches everything needed to write one: size, bubble, input, sandbox rules, state and requests, sending, and which chats accept a widget in production. Not for Mini Apps or Rich Messages.

tg-widgets

A widget is one self-contained HTML document with inline CSS and JS. A bot sends it as a message, and it runs in the chat bubble with no window, no server and no network. The HTML never changes after sending; only the bot changes the widget's state.

Everything needed to write a widget is below. The rules follow Telegram's widget-sandbox documentation, v0.6.0, checked on 2026-11-06. Bot API 10.4 (2026-11-09) made widgets official: the methods and the delivery rules are on core.telegram.org/bots/widgets, and where that page and the repository disagree, the page wins. For a detail not covered here, see docs/sdk-v1.md and docs/profile-v1.md in that repository.

Steps

  1. Write the widget by the rules below.

  2. Measure as the server does:

    python3 scripts/widget_tool.py check widget.html
    
  3. Send it to your private chat with the bot. The tool sends once and never retries: after a timeout the message may already be delivered.

    TELEGRAM_BOT_TOKEN=... python3 scripts/widget_tool.py send widget.html --chat CHAT_ID --caption "Tap the water to feed"
    
  4. Open it on a phone. A successful sendWidget proves only that the server accepted it: clients below layer 233 show an unsupported-media stub with the caption, so write a caption that makes sense alone.

Size

The server compresses the HTML with zlib level 9 and refuses anything over 4096 bytes, or over 32768 bytes raw, with INPUT_MEDIA_WIDGET_TOO_LARGE. Aim for 3800 if you cannot measure.

  • Repeated CSS and markup compress well. data: images and long unique text do not.
  • Non-ASCII text compresses badly: cutting Russian strings saved more than renaming identifiers.
  • Generate scenes in code instead of storing them.
  • No comments, no dead code. Minify with terser.

Bubble

  • 200–600 px wide, phones about 320–430: design for 320. Up to 600 px tall; the rest is clipped and nothing scrolls inside. Split long content into pages or tabs.
  • width and height in sendWidget set the size, 0 means auto. Lay out with %, flex, grid or vw, never vh.
  • html has no background: the bubble's colour shows through, and a background on html or body paints the whole bubble. body has a margin of about 8px 12px; body{margin:0} goes edge to edge.
  • Colours: --tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color, --tg-theme-button-color, --tg-theme-button-text-color, --tg-theme-secondary-bg-color; --tg-color-scheme is light or dark. Build on them so both themes work, or paint the whole bubble yourself.
  • Without a caption below, the client draws the message time over the bottom corner. Keep env(safe-area-inset-bottom) clear, and set body{padding:0} if you pad for it yourself.
  • Text is not selectable unless you set user-select:text and -webkit-user-select:text.

Input

Taps (click) and pointer events only. No touch events, keyboard, focus, text input, wheel or scroll events. A double tap is always the widget's.

Vertical drags belong to the chat, whatever touch-action says. So no vertical sliders, wheel pickers or free drawing: use horizontal controls or buttons.

touch-action on the elementUse forHoldHorizontal drag
auto (default)everything elsechat's message menuchat's swipe-to-reply
pan-yslider, carousel, paddlechat's menuwidget's
nonecanvas, game control, held buttonwidget'swidget's

The first move past 10 px decides the whole press: a drag that starts sideways on a claimed element stays with the widget on both axes, and one that starts up or down goes to the chat, and the widget gets pointercancel and no click. On pointercancel, undo what pointerdown started. The leading 20 px never take a claim because of the system back gesture: keep controls away from that edge.

What works

  • HTML: text elements, lists, tables, details, a, button (unstyled, it looks like the client's own), canvas, img with data: PNG, JPEG, GIF or WebP up to 1024×1024, inline SVG with shapes, paths, text, use and gradients.
  • CSS: flex, grid, positioning, shadows, gradients, 2D transforms, opacity, filter and backdrop-filter with blur(), brightness() and drop-shadow() only, transitions, @keyframes, custom properties, calc, @media on width, prefers-color-scheme, @supports. Fonts: system-ui, sans-serif, serif, monospace, ui-* only.
  • JS: ES2023 in an interpreter without JIT, timers, requestAnimationFrame, the DOM, canvas 2D (paths, arcs, fillText, gradients, setTransform, clip, drawImage), el.animate, Intl, crypto.getRandomValues, localStorage, sessionStorage. Use document.getElementById('x'): ids are not global variables.

Not available

Removed silently while the rest keeps running, so a removed feature is a bug you will not see.

  • Network: fetch, XMLHttpRequest, WebSocket throw NetworkDisabledError; nothing external loads.
  • Canvas: WebGL, OffscreenCanvas, getImageData, putImageData, createImageData, toDataURL, shadowBlur, globalCompositeOperation, ctx.filter, createPattern from a canvas.
  • CSS: 3D transforms, perspective, vh, overflow:auto|scroll, position:sticky, text-shadow, clip-path, mask, mix-blend-mode, background-clip:text, color-mix, oklch, @font-face, named fonts, @container, :has, CSS nesting.
  • HTML: form controls, audio, video, iframe, dialog, progress.
  • JS: libraries, Worker, alert, confirm, navigator.clipboard, window.open, location changes, Blob, customElements.

TelegramWidget

window.TelegramWidget is undefined outside Telegram, so guard it.

MemberPurpose
ready()optional, first state drawn
colorScheme, themeParams, onEvent('themeChanged', fn)theme
HapticFeedback.impactOccurred('light'), .notificationOccurred('success'), .selectionChanged()haptics: free during a touch and 5 s after it, otherwise one short series per 10 s
openLink(url), openTelegramLink(url), copyText(text), request(data)need a real tap: call in a click handler, one per tap, not after await or a timer
chatData, publicData, onEvent('chatDataChanged', fn), onEvent('publicDataChanged', fn)state written by the bot, up to 1024 bytes of text or null
watchPublicData()poll the shared state live while on screen
viewer, isForward, chatType, isPreviewwho looks and where; viewer is null where the widget may not ask the bot
walletGram Wallet; null where unavailable. See docs/sdk-v1.md §2.18

State and requests

  • chatData belongs to this message in its chat: a game in progress, whose turn it is. A forward never gets it.
  • publicData is seen wherever the widget is shown: poll results, a price. A forward gets a frozen copy, or the live value if the bot sent the widget with is_shared.
  • localStorage is this user's own, per message and device, 4 KB; catch QuotaExceededError. Use it for a best score or a seed.
  • request(data) works like a callback button: 1–64 bytes, resolves with {result} up to 1024 bytes, rejects with error.code: NOT_ALLOWED, BUSY, RATE_LIMITED, TIMEOUT, FAILED, INVALID_ANSWER. It needs allow_queries at sending. The answer does not change the state: have the bot edit it, or return the new state in result.

Lifecycle and limits

The widget can be destroyed and recreated at any time: restore from localStorage and the state, and draw the first frame synchronously. Off screen there are no animation frames and timers fire at most once per second.

LimitValue
CPU300 ms per second; one task up to 500 ms, longer stops the widget
Memory, nodes8 MB, 2000 nodes
Canvas4000 commands per canvas per task, 2048×2048 pixels in total
Paint16 elements with blurred shadow, filter or opacity below 1; 2 with backdrop-filter. Mute with colour instead of opacity
Layout reads128 per task; cache them and never read every frame
Other64 timers, 400 CSS rules, 32 @keyframes, 64 script animations

Past a limit the widget stops on its last frame with a "Widget stopped" badge.

Skeleton

<style>body{margin:0}canvas{display:block;width:100%;touch-action:none;image-rendering:pixelated}</style>
<canvas id="c"></canvas>
<script>
const T=window.TelegramWidget,c=document.getElementById('c'),x=c.getContext('2d');
const W=c.clientWidth||360,H=Math.round(W*9/16),S=3;
c.style.height=H+'px';c.width=W/S|0;c.height=H/S|0;
let last=0;
function frame(t){requestAnimationFrame(frame);if(t-last<33)return;last=t;
  x.fillStyle='#024';x.fillRect(0,0,c.width,c.height)}
c.addEventListener('click',e=>{const r=c.getBoundingClientRect();
  T&&T.HapticFeedback.selectionChanged()});
requestAnimationFrame(frame);T&&T.ready();
</script>

Delivery: production and live check

Widgets roll out in steps. On the test server groups, forum topics, inline mode and forwards work too. In production a bot sends widgets only to private chats: Bot API 10.4 and the official page say so. Live means real requests with a production bot on 2026-11-10; a row marked 2026-11-06 was not retried. Recheck before you plan around it.

TargetDocumentation, productionLive
api.telegram.org/bot<token>/sendWidgetthe documented pathworks, HTTP 200; was 404 on 2026-11-06
api.telegram.org/beta/bot<token>/sendWidgetnot mentioned any moreworks
Private chat with the botallowedworks, rendered on an iPhone
Basic group or supergroup with the bottest server only; the bot needs can_send_other_messages2026-11-06: supergroup and a channel's discussion group refused: INPUT_MEDIA_WIDGET_NOT_ALLOWED
Forum topic, message_thread_idtest server onlynot tried
Channel, direct or via the botrefused, on the test server too2026-11-06: refused, same error
Inline modetest server only2026-11-06: refused in a channel, and for a query from the private chat with the bot
forwardMessagerefused: every widget has protected contentrefused: the message can't be forwarded
copyMessagerefusedrefused: the message can't be copied

Forwards do not exist in production yet, so isForward and the forwarded copy of publicData matter only on the test server.

To put a widget in front of a group, forum topic or channel audience today, post an ordinary message there with a t.me/<bot>?start=... link, and let the bot send the widget in the private chat.

Bot API

MethodPurpose
sendWidgetchat_id, message_thread_id (forum supergroups and private chats with topics), html, width, height (0 = auto), chat_data, public_data, caption, allow_queries, is_shared, reply_markup
sendSharedWidgetpost an existing shared widget again by widget_id
editMessageWidgetDatachange chat_data or public_data of one message silently; message is not modified counts as done
editSharedWidgetDatachange the state of a shared widget everywhere, cache_time 5–3600 s
answerWidgetQueryanswer the widget_query or shared_widget_query update, always, or the widget gets TIMEOUT

Examples

examples/ holds widgets built with this skill and opened on an iPhone. They show one author's look. examples/index.html runs all four on one page in a browser, without Telegram. Sizes after zlib level 9:

FileBytes
aquarium-pixel.html4080
night-deploy-pixel.html4086
night-deploy-textmode.html4071
textmode-panel.html2134
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall