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

telegram-widgets

/telegram-widgets

Buduje i zabezpiecza widgety HTML Bot API 10.4 Telegrama, czyli interaktywne mini interfejsy w wiadomościach czatu.

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
15
Skrypty
5
Komentarze HTML
0
Adresy URL w SKILL.md
5
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ą
  • 5 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: adapters/node-fetch.mjs, adapters/python-aiogram.py, adapters/python-stdlib.py, scripts/check_widget.py, scripts/preview_widget.py

Co robi i kiedy

Buduje i zabezpiecza widgety HTML Bot API 10.4 Telegrama, czyli interaktywne mini interfejsy w wiadomościach czatu.

Oryginalny opis (EN)

Build, ship and secure Telegram Bot API 10.4+ HTML widgets, the interactive mini-UIs a bot sends inside a chat message (sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData, editSharedWidgetData, widget_query and shared_widget_query updates, the TelegramWidget JavaScript object). Language- and framework-agnostic; works for bots in Python, Node.js, Go, PHP or anything that speaks HTTP. Use this skill whenever a user wants to add an interactive message, live progress bar, poll, picker, editor, mini-game, ticker, counter or quiz to a Telegram bot, migrate callback-button flows t

Jak działa

  1. What to read
  2. Workflow
  3. Defaults when the user did not specify
Sekcje z nagłówków SKILL.md, w oryginale · 150 linii, 1 354 słów
Podgląd SKILL.md
---
name: telegram-widgets
description: Build, ship and secure Telegram Bot API 10.4+ HTML widgets, the interactive mini-UIs a bot sends inside a chat message (sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData, editSharedWidgetData, widget_query and shared_widget_query updates, the TelegramWidget JavaScript object). Language- and framework-agnostic; works for bots in Python, Node.js, Go, PHP or anything that speaks HTTP. Use this skill whenever a user wants to add an interactive message, live progress bar, poll, picker, editor, mini-game, ticker, counter or quiz to a Telegram bot, migrate callback-button flows to widgets, debug a widget that looks different in Telegram than in a browser, or hits INPUT_MEDIA_WIDGET_TOO_LARGE, BUSY, NOT_ALLOWED or TIMEOUT, even if they only say "make the bot message interactive" and never say "widget".
license: MIT
metadata:
  author: Artem Islamov
  website: https://islamov-tema.ru
  repository: https://github.com/aislam23/telegram-widgets-skill
---

# Telegram widgets

A widget is one self-contained HTML document that a bot sends as a message. Telegram apps run it on the
user's device in a QuickJS sandbox with no network, draw it in the chat's colors and keep it alive while
it is on screen. The widget **cannot change its own state**: only the bot writes state, and the widget
can only *ask* the bot with tiny requests. Everything in this skill follows from that split.

```
 bot ──sendWidget(html, chat_data, public_data)──▶ message ──▶ widget runs on the device
 bot ◀──────────── widget_query (≤64 bytes, on a tap) ─────── widget
 bot ──answerWidgetQuery (≤1024 bytes, to the asker only)──▶ widget (its promise resolves)
 bot ──editMessageWidgetData (new state)────────────────────▶ widget gets chatDataChanged
```

The bot side is plain HTTPS calls to the Bot API, so this works in any language. Official docs:
https://core.telegram.org/bots/widgets and https://core.telegram.org/bots/api. Re-read them if they are
newer than this skill: the feature is rolling out in steps and limits may change.

## What to read

| You need | Read |
|---|---|
| Methods, fields, limits, allowed HTML/CSS/JS, the `TelegramWidget` API | `references/platform.md` |
| Security checklist (for every widget) | `references/security.md` |
| Bugs that only appear in real Telegram, and their fixes | `references/pitfalls.md` |
| Bot-side architecture in pseudocode (any language) | `references/server-side.md` |
| Reaching widget calls from a framework that predates 10.4 | `references/frameworks.md` |
| Proven designs: live progress, editor with autostart, poll, ticker | `references/patterns.md` |
| Size checks, local preview, live test plan | `references/testing.md` |

Files to start from:
- `templates/widget-skeleton.html`: the widget side, safe defaults built in.
- `adapters/`: working bot-side code for Python + aiogram, Python stdlib, Node.js (fetch) and curl.
  Use the one matching the user's stack, or port it: the logic is the same everywhere.
- `scripts/check_widget.py`: compressed size and forbidden-feature lint (needs Python 3 to run, checks
  widgets for bots in any language). `scripts/preview_widget.py`: local browser preview with a stub.

## Workflow

Follow the steps in order. Most real failures came from skipping step 1 or step 6.

### 1. Check where the widget will live

As of Bot API 10.4 **production supports widgets only in the private chat with the bot**. Groups, inline
mode and forwarding work only on the test server, and production widgets are automatically
`protect_content` (cannot be forwarded). Channels never accept widgets. If the plan depends on groups,
inline results or viral forwarding, say so up front and design a private-chat version or an explicit
test-server path.

Check the user's bot library. Most libraries released before 10.4 do not know the new methods or the
`widget_query` update; `references/frameworks.md` shows the escape hatches.

### 2. Design the protocol before writing HTML

Write it down as a comment in the bot code:

- **chat_data** (per message, ≤1024 bytes UTF-8): what the widget renders. Compact JSON with short keys
  and a mode field, e.g. `{"m":"p","st":1,"p":64}`. The bot holds the authoritative copy and always
  sends the whole object.
- **public_data** (≤1024 bytes): shared state, or, for a static widget, a free slot for constant data
  such as UI strings (see the size budget).
- **requests** (1–64 bytes): a tiny grammar such as `h`, `g:x,y,z,s`, `f`. Each must be answerable in
  well under 15 seconds; slow work happens after answering.
- **answers** (≤1024 bytes): what the widget shows immediately (`ok` or a short error sentence).
- **modes**: which state the bot pushes when, and what the widget shows in each, including errors and
  waiting states.

Non-Latin text costs 2–3 bytes per character in every budget.

### 3. Plan the 4 KB budget

The HTML may be 32 KB raw but must be **≤4096 bytes after zlib level 9**, counted by the server. Aim for
≤4000. A typical spend: CSS ~450 B, logic 1.5–2.5 KB, ~400 B for twenty Russian UI strings, the rest for
images. Tactics in order of payoff:

1. Move constant UI strings into `public_data` (static widgets) and index them (`T[3]`).
2. Prefer SVG and CSS to images; `data:` images barely compress.
3. If an image is essential, make it server-side and shrink it in a loop until the compressed HTML fits
   (WebP first, JPEG fallback). See `references/patterns.md` §7.
4. Hand-minify: short identifiers, no comments, shared helpers. Minifiers save only 5–10%.

Run `python3 scripts/check_widget.py widget.html` after every change.

### 4. Build the widget from the skeleton

Start from `templates/widget-skeleton.html`. It already handles what broke in practice: it renders
synchronously from `TelegramWidget.chatData` and on `chatDataChanged`; it keeps one request in flight,
queues a primary action pressed meanwhile, catches synchronous throws and resets flags on rejection; it
writes non-constant text with `textContent`; it uses theme variables; it runs outside Telegram for
previews.

Rules that are easy to forget (details in `references/platform.md`):

- `request()`, `openLink()`, `copyText()` only inside a **click or pointerup** handler, synchronously.
  One tap unlocks one call. In the private chat a few background requests are allowed without a tap.
- Vertical drags always scroll the chat. The widget gets taps, and horizontal drags only on elements
  with `touch-action: pan-y`. On `pointercancel`, undo whatever `pointerdown` started.
- The leading 20 px never claim gestures (system back swipe).
- No `<input>`, `<select>`, `<video>`, `<audio>`, `<iframe>`, no `fetch`, no `vh`, no `color-mix()`,
  no `oklch()`, no `overflow: auto`, no web fonts. `<button>` is the only form control.
- At most 16 elements with `opacity < 1`, filters or blurred shadows at once: mute with colors.
- Height 50–600 px and nothing scrolls inside; stay under ~560 px at 320 px width.
- Canvas: no hole-punching paths; dim everything, then clip and redraw (pitfall 1).
- Send a caption. Apps without widget support show only the caption, and with a caption below the
  widget the message time does not cover its corner.

### 5. Build the bot side

Follow `references/server-side.md` and start from the matching file in `adapters/`. Non-negotiables,
explained in `references/security.md`:

1. **Subscribe to the updates**: list `widget_query` (and `shared_widget_query` if used) in
   `allowed_updates`, or requests time out silently.
2. **Answer every query** with `answerWidgetQuery` within 15 s, also on errors, before slow work.
3. **Authorize**: match `from.id` with the owner stored for `(chat_id, message_id)`, or key by
   `(widget_id, from.id)` for shared widgets. `from` and `widget_id` cannot be forged; `data` can.
4. **Parse `data` strictly** with an anchored pattern and a length cap; clamp every number.
5. **Keep authoritative state on the server**, keyed by the message, persisted with a TTL when buttons
   must work after a restart. Commit a user's move only after the edit succeeded.
6. **Guard concurrency**: register busy and waiting records immediately after `sendWidget` returns,
   before any other await; serialize edits per message; make error states terminal; never hold a shared
   lock while waiting for a human.
7. **Respect rate limits**: each `editMessageWidgetData` counts as a sent message; push mode changes at
   once and percentages at most every 1–2 s. Shared widgets: one edit per second.
8. **Never leak secrets** in HTML, state, answers, captions, user-facing errors or logs. Raw exception
   text from HTTP clients can contain `https://api.telegram.org/file/bot<TOKEN>/…`.
9. **Fallback and kill switch**: if `sendWidget` fails, use the previous text/keyboard flow; keep a
   `WIDGETS_ENABLED` flag.

### 6. Verify in real Telegram, not only in a browser

A browser renders more than Telegram and hides renderer differences. Always:

1. `scripts/check_widget.py`: size and forbidden features pass.
2. `scripts/preview_widget.py`: every mode renders at 320–430 px, light and dark.
3. Send it from a test bot to a real account and walk through every mode, errors, a slow network, two
   quick taps, and scrolling the widget away and back (`references/testing.md`).
4. Tell the user exactly what was verified live and what was only previewed.

## Defaults when the user did not specify

- A static widget (`sendWidget` without `is_shared`) in the private chat; `allow_queries` only when the
  widget must talk to the bot.
- Always a caption that makes sense on its own.
- Long jobs: one widget per job, state pushed by the bot, percentages throttled.
- Choices with a sensible default: an editor that auto-continues with the default after a short
  countdown unless the user touches it (`references/patterns.md` §3).
- The old non-widget flow stays available behind a feature flag.
Pliki w paczce (15)
  • SKILL.md 10 KB
  • adapters/curl.md 2 KB
  • adapters/node-fetch.mjs 3 KB
  • adapters/python-aiogram.py 10 KB
  • adapters/python-stdlib.py 3 KB
  • references/frameworks.md 3 KB
  • references/patterns.md 5 KB
  • references/pitfalls.md 8 KB
  • references/platform.md 11 KB
  • references/security.md 9 KB
  • references/server-side.md 5 KB
  • references/testing.md 3 KB
  • scripts/check_widget.py 7 KB
  • scripts/preview_widget.py 5 KB
  • templates/widget-skeleton.html 3 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · aislam23/telegram-widgets-skill100MIT
kbgod/lumex100MIT
vitalikgpt/catalogue-app-plugin90MIT

Migawka bazy z 13.11.2026 · wersja paczki f430c3d15039 (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

  • 95telegram-bot-widgets
    Buduje, wysyła i obsługuje interaktywne widgety HTML w wiadomościach bota Telegram, w tym quizy, wykresy i gry.
  • 100tgcloud-widgets
    Buduje widgety HTML Bot API 10.4 dla bota na tgcloud, np. licznik, ankietę lub grę, ze stanem i obsługą zapytań.
  • 100tg-widgets
    Tworzy i wysyła widgety HTML w dymku wiadomości Telegrama, np. grę, ankietę lub kalkulator, z zasadami piaskownicy.
  • 95telegram-api-skill
    Buduje, debuguje i sprawdza boty Telegram, Mini Apps, płatności Stars, boty biznesowe i klientów MTProto.
  • 90Telegram Bot Builder
    Pomaga tworzyć boty Telegrama: webhooki, klawiatury inline, callback queries, płatności, wysyłanie mediów, komendy i wdrożenie, z użyciem Telegram Bot API oraz bibliotek botów.
  • 90telegram-bot-api
    Zawiera bazę wiedzy i narzędzia do pisania botów Telegrama oraz Mini Apps: webhooki, płatności Stars, limity i walidację initData.

Uwagi i zgłoszenia

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