serejaris/telegram-skills / skills/tg-widgets
tg-widgets
VerifiedUse 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
-
Write the widget by the rules below.
-
Measure as the server does:
python3 scripts/widget_tool.py check widget.html -
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" -
Open it on a phone. A successful
sendWidgetproves 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.
widthandheightinsendWidgetset the size,0means auto. Lay out with%, flex, grid orvw, nevervh.htmlhas no background: the bubble's colour shows through, and a background onhtmlorbodypaints the whole bubble.bodyhas a margin of about8px 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-schemeis 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 setbody{padding:0}if you pad for it yourself. - Text is not selectable unless you set
user-select:textand-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 element | Use for | Hold | Horizontal drag |
|---|---|---|---|
auto (default) | everything else | chat's message menu | chat's swipe-to-reply |
pan-y | slider, carousel, paddle | chat's menu | widget's |
none | canvas, game control, held button | widget's | widget'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,imgwithdata:PNG, JPEG, GIF or WebP up to 1024×1024, inline SVG with shapes, paths, text,useand gradients. - CSS: flex, grid, positioning, shadows, gradients, 2D transforms,
opacity,filterandbackdrop-filterwithblur(),brightness()anddrop-shadow()only, transitions,@keyframes, custom properties,calc,@mediaon 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. Usedocument.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,WebSocketthrowNetworkDisabledError; nothing external loads. - Canvas: WebGL,
OffscreenCanvas,getImageData,putImageData,createImageData,toDataURL,shadowBlur,globalCompositeOperation,ctx.filter,createPatternfrom 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,locationchanges,Blob,customElements.
TelegramWidget
window.TelegramWidget is undefined outside Telegram, so guard it.
| Member | Purpose |
|---|---|
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, isPreview | who looks and where; viewer is null where the widget may not ask the bot |
wallet | Gram Wallet; null where unavailable. See docs/sdk-v1.md §2.18 |
State and requests
chatDatabelongs to this message in its chat: a game in progress, whose turn it is. A forward never gets it.publicDatais 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 withis_shared.localStorageis this user's own, per message and device, 4 KB; catchQuotaExceededError. 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 witherror.code:NOT_ALLOWED,BUSY,RATE_LIMITED,TIMEOUT,FAILED,INVALID_ANSWER. It needsallow_queriesat sending. The answer does not change the state: have the bot edit it, or return the new state inresult.
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.
| Limit | Value |
|---|---|
| CPU | 300 ms per second; one task up to 500 ms, longer stops the widget |
| Memory, nodes | 8 MB, 2000 nodes |
| Canvas | 4000 commands per canvas per task, 2048×2048 pixels in total |
| Paint | 16 elements with blurred shadow, filter or opacity below 1; 2 with backdrop-filter. Mute with colour instead of opacity |
| Layout reads | 128 per task; cache them and never read every frame |
| Other | 64 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.
| Target | Documentation, production | Live |
|---|---|---|
api.telegram.org/bot<token>/sendWidget | the documented path | works, HTTP 200; was 404 on 2026-11-06 |
api.telegram.org/beta/bot<token>/sendWidget | not mentioned any more | works |
| Private chat with the bot | allowed | works, rendered on an iPhone |
| Basic group or supergroup with the bot | test server only; the bot needs can_send_other_messages | 2026-11-06: supergroup and a channel's discussion group refused: INPUT_MEDIA_WIDGET_NOT_ALLOWED |
Forum topic, message_thread_id | test server only | not tried |
| Channel, direct or via the bot | refused, on the test server too | 2026-11-06: refused, same error |
| Inline mode | test server only | 2026-11-06: refused in a channel, and for a query from the private chat with the bot |
forwardMessage | refused: every widget has protected content | refused: the message can't be forwarded |
copyMessage | refused | refused: 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
| Method | Purpose |
|---|---|
sendWidget | chat_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 |
sendSharedWidget | post an existing shared widget again by widget_id |
editMessageWidgetData | change chat_data or public_data of one message silently; message is not modified counts as done |
editSharedWidgetData | change the state of a shared widget everywhere, cache_time 5–3600 s |
answerWidgetQuery | answer 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:
| File | Bytes |
|---|---|
aquarium-pixel.html | 4080 |
night-deploy-pixel.html | 4086 |
night-deploy-textmode.html | 4071 |
textmode-panel.html | 2134 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |