Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

tg-widgets

/tg-widgets

Tworzy i wysyła widgety HTML w dymku wiadomości Telegrama, np. grę, ankietę lub kalkulator, z zasadami piaskownicy.

Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/widget_tool.py, tests/test_widget_tool.py

Co robi i kiedy

Tworzy i wysyła widgety HTML w dymku wiadomości Telegrama, np. grę, ankietę lub kalkulator, z zasadami piaskownicy.

Oryginalny opis (EN)

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.

Jak działa

  1. Steps
  2. Size
  3. Bubble
  4. Input
  5. What works
  6. Not available
  7. TelegramWidget
  8. State and requests
  9. Lifecycle and limits
  10. Skeleton
Sekcje z nagłówków SKILL.md, w oryginale · 168 linii, 1 704 słów
Podgląd SKILL.md
---
name: tg-widgets
description: "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."
license: MIT
---

# 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`](https://github.com/TelegramMessenger/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](https://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:

   ```bash
   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.

   ```bash
   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 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`, `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.

| 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

- `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.

| 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

```html
<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`](examples/index.html) runs all four on one page in a browser, without Telegram. Sizes after zlib level 9:

| File | Bytes |
|---|---|
| [`aquarium-pixel.html`](examples/aquarium-pixel.html) | 4080 |
| [`night-deploy-pixel.html`](examples/night-deploy-pixel.html) | 4086 |
| [`night-deploy-textmode.html`](examples/night-deploy-textmode.html) | 4071 |
| [`textmode-panel.html`](examples/textmode-panel.html) | 2134 |
Pliki w paczce (8)
  • SKILL.md 12 KB
  • examples/aquarium-pixel.html 7 KB
  • examples/index.html 5 KB
  • examples/night-deploy-pixel.html 7 KB
  • examples/night-deploy-textmode.html 7 KB
  • examples/textmode-panel.html 4 KB
  • scripts/widget_tool.py 2 KB
  • tests/test_widget_tool.py 1 KB

Wersje

W bazie nie ma innych skilli o nazwie tg-widgets.

Migawka bazy z 13.11.2026 · wersja paczki ed8e82c01cf3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100tgcloud-widgets
    Buduje widgety HTML Bot API 10.4 dla bota na tgcloud, np. licznik, ankietę lub grę, ze stanem i obsługą zapytań.
  • 95telegram-bot-widgets
    Buduje, wysyła i obsługuje interaktywne widgety HTML w wiadomościach bota Telegram, w tym quizy, wykresy i gry.
  • 100telegram-widgets
    Buduje i zabezpiecza widgety HTML Bot API 10.4 Telegrama, czyli interaktywne mini interfejsy w wiadomościach czatu.
  • 100telegram-widgets
    Wyjaśnia zasady widgetów HTML Telegrama: dozwolony kod, limity bajtów i cykl zapytań z botem w Go.
  • 95telegram-api-skill
    Buduje, debuguje i sprawdza boty Telegram, Mini Apps, płatności Stars, boty biznesowe i klientów MTProto.
  • 100widget
    Tworzy, aktualizuje, ukrywa, pokazuje, wyświetla i usuwa widgety pulpitu Übersicht na macOS.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.