# tg-bot-ops

Adopt this skill: https://proskills.md/skills/other/serejaris-telegram-skills-skills-tg-bot-ops

Page: https://proskills.md/skills/other/serejaris-telegram-skills-skills-tg-bot-ops
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/tg-bot-ops/SKILL.md
size: 11792
sha: a892bb93280971327d2024dc4163121eb1ebb454
upstream: https://github.com/serejaris/telegram-skills/blob/main/skills/tg-bot-ops/SKILL.md

````text
---
name: tg-bot-ops
description: "Use when running a Telegram bot in production: webhook or long polling, allowed_updates, webhook secret token, privacy mode, 429 and retry_after, file retries, broadcast limits and paid broadcasts, lost updates on shutdown, a poison update after new Bot API types, t.me outage and fallback domains, local Bot API server."
license: MIT
---

# tg-bot-ops

Checked against the official docs on 2026-10-30: Bot API 10.3 (August 24, 2026). Reports from trackers are labeled with their date. No scenario here was run against a live bot; [scripts/retry_policy.py](scripts/retry_policy.py) has unit tests on simulated responses.

## Webhook or polling

Mutually exclusive. Either way, Telegram keeps undelivered updates [at most 24 hours](https://core.telegram.org/bots/api#getting-updates).

| | Long polling | Webhook |
|---|---|---|
| Fits | one process, no public HTTPS, a local machine | several workers, serverless |
| Ack | next `getUpdates` with a higher `offset` | your 2xx response |
| Limits | `limit` 1-100, `timeout` above 0 | ports 443, 80, 88, 8443; `max_connections` 1-100, default 40 |
| Failure | the same updates return until `offset` moves | non-2xx is repeated, then Telegram gives up "after a reasonable amount of attempts" |

Switching: `getUpdates` doesn't work while a webhook is set; use `deleteWebhook`. Keep `drop_pending_updates` off on a selling bot: it discards unprocessed `successful_payment` messages too.

Monitor `getWebhookInfo`: `pending_update_count`, `last_error_message`, `last_error_date`, `allowed_updates`.

A reply in the webhook response body (`method` plus parameters) saves a request, but its success and result can't be known. Use a normal request for anything you must confirm.

Webhook setup:

1. `setWebhook` with `secret_token`: 1-256 characters of `A-Za-z0-9_-`.
2. Reject any request whose `X-Telegram-Bot-Api-Secret-Token` header differs, using a constant-time compare.
3. Store the update durably, return 2xx, and process it afterwards. Answer `pre_checkout_query` right in the handler, ahead of any queue: it expires in 10 seconds (`tg-stars-payments`).

## allowed_updates

- Omitted: **the previous setting stays**. A list set once survives every deploy, so a new feature's update type never arrives until you pass a new list.
- Empty list: all types except `chat_member`, `message_reaction` and `message_reaction_count`, which need explicit opt-in and admin rights.
- A change doesn't affect updates created before the call.

Send the full list on startup and compare it with `getWebhookInfo.allowed_updates`. Types added in 2026: `guest_message`, `managed_bot`, `subscription`, `stopped_message_generation`.

## Privacy mode

On by default. In groups the bot sees commands meant for it, replies to it and messages sent via it, plus all service messages. An admin bot sees everything. After turning it off in @BotFather, re-add the bot to each group for the change to [take effect](https://core.telegram.org/bots/features#privacy-mode).

## 429 and retries

Documented [limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this): about 1 message per second per chat (short bursts allowed), 20 per minute in a group, about 30 per second for bulk. Treat the numbers as approximate and let `retry_after` rule. Flood limits are not raised in the [test environment](https://core.telegram.org/bots/features#dedicated-test-environment) and may at times be stricter, and a [maintainer says](https://github.com/tdlib/telegram-bot-api/issues/677) the local server doesn't change them (2024-12-13). `answerCallbackQuery` has no limit, editing is under the per-chat limit ([maintainer, 2024-10-09](https://github.com/tdlib/telegram-bot-api/issues/648)).

| Response | Meaning | Action |
|---|---|---|
| 429 with `parameters.retry_after` | not applied | hold the whole scope that long, then repeat |
| `parameters.migrate_to_chat_id` | group became a supergroup | store the new id, repeat |
| other 4xx | rejected | fix the request; 403 usually means the user blocked the bot |
| 5xx, timeout, dropped connection, non-JSON | **unknown**, it may have been delivered | report it and reconcile; resend only if a duplicate is harmless |

```python
import retry_policy as rp

gate = rp.FloodGate()                       # one per process

def make_request():                         # called on every attempt
    return build_multipart(url, fields, open(path, 'rb'))

decision = rp.send(make_request, transport, gate, f'chat:{chat_id}')
if decision.action == rp.UNKNOWN:
    park_for_reconcile(decision.reason)     # never treat this as a failed send
```

`transport(request)` is yours: it returns `(status, body)`, it should close the file, and any exception it raises counts as **unknown**, because the bytes may have left. `make_request` runs outside that guard: when it raises, for example on a missing file, nothing was sent and the exception reaches you.

`FloodGate` lives in the memory of one process. Several workers need a shared store for pauses, for example Redis with a key per scope and a TTL of `retry_after`.

The pause length belongs to the server: `Decision.wait` carries `retry_after` as received. `send` sleeps up to `max_inline_wait` (60 seconds by default). A longer pause comes back as `FAIL` with the real `wait`, so a handler can reschedule the send and free its worker.

Two failure modes this shape avoids, both reported in libraries in 2026:

- **Stale multipart.** Retrying a consumed upload fails with "media not found" ([grammY #862](https://github.com/grammyjs/grammY/issues/862), fixed 2026-01-16). The factory rebuilds the body each attempt.
- **Pause lifted early.** A shared event let any finishing request end the `RetryAfter` pause ([PTB #5338](https://github.com/python-telegram-bot/python-telegram-bot/issues/5338), closed 2026-09-13). `FloodGate` ends a pause by clock only. aiogram has no built-in rate limiter yet ([#1875](https://github.com/aiogram/aiogram/issues/1875), open on 2026-10-30).

Scope the gate by chat for sends, and by bot for a broadcast. For bulk, a queue at 30 per second or fewer is cheaper than handling 429s.

### Paid broadcasts

`allow_paid_broadcast: true` raises the limit to 1000 messages per second, at 0.1 Star per message above the free 30. Eligibility is stated two ways, and [@BotFather](https://t.me/botfather) decides:

| Source | Requirement | Checked |
|---|---|---|
| [Bot API page](https://core.telegram.org/bots/api#paid-broadcasts) | 10,000 Stars on the balance | 2026-10-30 |
| [Bot FAQ](https://core.telegram.org/bots/faq#how-can-i-message-all-of-my-bots-subscribers-at-once), [Terms § 6.2.5](https://telegram.org/tos/bot-developers#6-2-5-broadcasting-messages-with-stars) | 100,000 Stars and 100,000 monthly active users | 2026-10-30 |

## Not losing updates

- An update counts as confirmed the moment `getUpdates` is called with a higher `offset`. Recalculate `offset` after every response and save the update first, so a crash replays it.
- **Shutdown.** Stop fetching, wait for running handlers, then exit. aiogram doesn't wait for handlers whose updates are already confirmed, so a running payment handler dies ([#1955](https://github.com/aiogram/aiogram/issues/1955), open on 2026-10-30).
- Duplicates happen: handlers are idempotent, by `update_id` for transport repeats and by the domain key for money (`tg-stars-payments`). After a week without updates the next `update_id` is [random](https://core.telegram.org/bots/api#update), so never assume it only grows across a gap.
- Webhook versus polling reliability: one practitioner lost messages on webhooks and fixed it with polling ([Reddit](https://www.reddit.com/r/TelegramBots/comments/1rrlzlb/built_a_monetized_ai_companion_bot_on_telegram/), self-report). No reproducible report exists either way; a durable inbox beats the choice of transport.

## Poison updates

New Bot API versions add fields and types without notice to old clients. A library that fails to decode one update never moves `offset`, and the bot stops. Bot API 10.3 did exactly that: `RichTextButton` made aiogram raise `ClientDecodeError` and block polling until 3.31 ([#1890](https://github.com/aiogram/aiogram/issues/1890), 2026-08-25). Deeply nested `rich_message.blocks` stalled validation with a single update ([#1842](https://github.com/aiogram/aiogram/issues/1842), 2026-06-29).

Before each Bot API version reaches users:

1. Read the raw JSON first, and persist it before typed parsing.
2. Put decoding inside a per-update guard. On failure, save the raw update to a dead-letter store, count it, and advance `offset` (or return 2xx).
3. Treat unknown fields and types as ignorable.
4. Alert on a repeating `update_id` and a growing `pending_update_count`.
5. Update your library when [the changelog](https://core.telegram.org/bots/api-changelog) moves, and test a replay of stored raw updates.

```python
for update in updates:
    store_raw(update)                       # before anything can fail
    try:
        handle(decode(update))
    except Exception as error:
        dead_letter(update, error)          # poison stops here, offset still moves
    offset = update['update_id'] + 1
```

A `successful_payment` in the dead-letter store still owes the buyer: replay it through the ledger, or follow the recovery rules in `tg-stars-payments`, because `getStarTransactions` lacks `subscription_expiration_date`.

## Domains

On 2026-07-13 at 19:24 UTC the `t.me` domain went down for about a day after an [OFAC listing](https://ofac.treasury.gov/recent-actions/20260713) named a `t.me` address; `telegram.me` kept working ([TechCrunch](https://techcrunch.com/2026/07/14/telegrams-shortlink-domain-is-back-online-after-day-long-suspension/), [Cybernews](https://cybernews.com/security/telegram-links-broken-after-domain-outage/)). No official post-mortem was found.

The fallback isn't universal. Reports from that day:

- Posts and bot links: `telegram.me` worked; profile images saved on `t.me` broke, and the swap fixed them ([HN](https://news.ycombinator.com/item?id=48898291)).
- Invoices: `createInvoiceLink` returned `telegram.me`, and the invoice did not open until the host was replaced with `t.me` ([PTB #5296](https://github.com/python-telegram-bot/python-telegram-bot/issues/5296)).
- Mini Apps: tma.js `openTelegramLink` rejected `telegram.me` and `telegram.dog` ([#879](https://github.com/Telegram-Mini-Apps/tma.js/issues/879), closed 2026-07-14).

So keep the host in one config value, avoid `t.me` allowlists in validators and store usernames instead of full links. A URL returned by the API can fail too: open an invoice on a client to check it, and test any fallback for invoices and Mini App links before relying on it.

## Local Bot API server

Run [tdlib/telegram-bot-api](https://github.com/tdlib/telegram-bot-api) for [these features](https://core.telegram.org/bots/api#using-a-local-bot-api-server): unlimited download, upload up to 2000 MB, `file://` paths, absolute `file_path` from `getFile`, HTTP webhooks on any port and local IP, `max_webhook_connections` up to 100000. Everything else, including flood limits, stays.

Moving a bot:

1. `logOut` before pointing it at the local server. The bot can't return to the cloud for 10 minutes.
2. Moving between local servers: `deleteWebhook`, then `close`. `close` returns 429 during the first 10 minutes after launch.
3. Put a TLS proxy in front; the local server speaks HTTP.

Done when `getMe` answers on the new URL and updates arrive there.

## Sources

- https://core.telegram.org/bots/api#getting-updates
- https://core.telegram.org/bots/api#setwebhook
- https://core.telegram.org/bots/api#getupdates
- https://core.telegram.org/bots/faq
- https://core.telegram.org/bots/webhooks
````

## File: skills/tg-bot-ops/scripts/retry_policy.py
size: 2866
sha: f8e4409fe83aa3b9230d97b0ecff50fbe400b1f4
upstream: https://github.com/serejaris/telegram-skills/blob/main/skills/tg-bot-ops/scripts/retry_policy.py

```text
from dataclasses import dataclass
import json
import time

DONE = 'done'
RETRY = 'retry'
MIGRATE = 'migrate'
FAIL = 'fail'
UNKNOWN = 'unknown'

DEFAULT_WAIT = 1
MAX_INLINE_WAIT = 60

@dataclass(frozen=True)
class Decision:
    action: str
    wait: int = 0
    chat_id: int | None = None
    reason: str = ''
    result: object = None

def _is_int(value):
    return isinstance(value, int) and not isinstance(value, bool)

def classify(status, body):
    if not _is_int(status):
        return Decision(UNKNOWN, reason='no HTTP status')
    try:
        data = json.loads(body)
    except (TypeError, ValueError):
        data = None
    if not isinstance(data, dict):
        return Decision(UNKNOWN, reason=f'HTTP {status} without a JSON object')
    if data.get('ok') is True and status < 300:
        return Decision(DONE, result=data.get('result'))
    params = data.get('parameters')
    params = params if isinstance(params, dict) else {}
    reason = str(data.get('description', f'HTTP {status}'))
    if status == 429:
        wait = params.get('retry_after')
        wait = wait if _is_int(wait) and wait > 0 else DEFAULT_WAIT
        return Decision(RETRY, wait=wait, reason=reason)
    migrate_to = params.get('migrate_to_chat_id')
    if _is_int(migrate_to) and migrate_to != 0:
        return Decision(MIGRATE, chat_id=migrate_to, reason=reason)
    if 400 <= status < 500:
        return Decision(FAIL, reason=reason)
    return Decision(UNKNOWN, reason=reason)

class FloodGate:
    def __init__(self, clock=time.monotonic, sleep=time.sleep):
        self._clock = clock
        self._sleep = sleep
        self._until = {}

    def hold(self, scope, wait):
        self._until[scope] = max(self._until.get(scope, 0), self._clock() + wait)

    def delay(self, scope):
        return max(0, self._until.get(scope, 0) - self._clock())

    def sleep(self, seconds):
        self._sleep(seconds)

def send(make_request, transport, gate, scope, max_attempts=3, max_inline_wait=MAX_INLINE_WAIT):
    if not _is_int(max_attempts) or max_attempts < 1:
        raise ValueError('max_attempts must be a positive integer')
    decision = Decision(UNKNOWN, reason='not attempted')
    for _ in range(max_attempts):
        pause = gate.delay(scope)
        if pause > max_inline_wait:
            return Decision(FAIL, wait=pause, reason=f'pause too long: {decision.reason}')
        if pause:
            gate.sleep(pause)
        request = make_request()
        try:
            status, body = transport(request)
        except Exception as error:
            return Decision(UNKNOWN, reason=f'transport: {error}')
        decision = classify(status, body)
        if decision.action != RETRY:
            return decision
        gate.hold(scope, decision.wait)
    return Decision(FAIL, wait=decision.wait, reason=f'still limited: {decision.reason}')
```

## File: skills/tg-bot-ops/tests/test_retry_policy.py
size: 6559
sha: eaae67690ca88b9696c450fdcf68a566e41898f7
upstream: https://github.com/serejaris/telegram-skills/blob/main/skills/tg-bot-ops/tests/test_retry_policy.py

```text
import importlib.util
import io
import json
from pathlib import Path
import sys
import unittest

SPEC = importlib.util.spec_from_file_location('retry_policy', Path(__file__).parents[1] / 'scripts/retry_policy.py')
policy = importlib.util.module_from_spec(SPEC)
sys.modules['retry_policy'] = policy
SPEC.loader.exec_module(policy)

def body(**fields):
    return json.dumps(fields)

LIMITED = (429, body(ok=False, error_code=429, description='Too Many Requests',
                     parameters={'retry_after': 7}))
SENT = (200, body(ok=True, result={'message_id': 1}))

class Clock:
    def __init__(self):
        self.now = 100
        self.slept = []

    def __call__(self):
        return self.now

    def sleep(self, seconds):
        self.slept.append(seconds)
        self.now += seconds

class Classify(unittest.TestCase):
    def test_success(self):
        decision = policy.classify(*SENT)
        self.assertEqual((decision.action, decision.result), (policy.DONE, {'message_id': 1}))

    def test_retry_after_is_honored(self):
        decision = policy.classify(*LIMITED)
        self.assertEqual((decision.action, decision.wait), (policy.RETRY, 7))

    def test_bad_retry_after_falls_back(self):
        for value in (None, 0, -5, '7', True, 1.5):
            params = {'retry_after': value}
            decision = policy.classify(429, body(ok=False, parameters=params))
            self.assertEqual((decision.action, decision.wait), (policy.RETRY, policy.DEFAULT_WAIT))
        self.assertEqual(policy.classify(429, body(ok=False, parameters='x')).wait, policy.DEFAULT_WAIT)

    def test_huge_retry_after_is_kept(self):
        decision = policy.classify(429, body(ok=False, parameters={'retry_after': 7200}))
        self.assertEqual((decision.action, decision.wait), (policy.RETRY, 7200))

    def test_group_migration(self):
        decision = policy.classify(400, body(ok=False, parameters={'migrate_to_chat_id': -1001234567890}))
        self.assertEqual((decision.action, decision.chat_id), (policy.MIGRATE, -1001234567890))

    def test_rejected_requests_fail(self):
        for status in (400, 401, 403, 404):
            self.assertEqual(policy.classify(status, body(ok=False, description='no')).action, policy.FAIL)

    def test_unclear_outcomes_are_unknown(self):
        for status, raw in ((500, body(ok=False)), (502, '<html>bad gateway</html>'), (200, 'not json'),
                            (200, '[]'), (200, 'null'), (200, ''), (200, None), (200, b'\xff'),
                            (200, body(ok=False)), (None, body(ok=True)), ('200', body(ok=True))):
            with self.subTest(status=status, raw=raw):
                self.assertEqual(policy.classify(status, raw).action, policy.UNKNOWN)

class Gate(unittest.TestCase):
    def test_finished_request_does_not_lift_the_pause(self):
        clock = Clock()
        gate = policy.FloodGate(clock, clock.sleep)
        gate.hold('chat:1', 10)
        clock.now = 103
        self.assertEqual(gate.delay('chat:1'), 7)
        self.assertEqual(gate.delay('chat:2'), 0)
        clock.now = 111
        self.assertEqual(gate.delay('chat:1'), 0)

    def test_shorter_wait_does_not_shrink_the_pause(self):
        clock = Clock()
        gate = policy.FloodGate(clock, clock.sleep)
        gate.hold('bot', 10)
        clock.now = 101
        gate.hold('bot', 1)
        self.assertEqual(gate.delay('bot'), 9)

class Send(unittest.TestCase):
    def run_send(self, responses, make_request=None, **kwargs):
        clock = Clock()
        queue = list(responses)
        seen = []

        def transport(request):
            seen.append(request)
            item = queue.pop(0)
            if isinstance(item, Exception):
                raise item
            return item

        decision = policy.send(make_request or (lambda: 'request'), transport,
                               policy.FloodGate(clock, clock.sleep), 'chat:1', **kwargs)
        return decision, seen, clock

    def test_multipart_is_rebuilt_for_every_attempt(self):
        built = []

        def make_request():
            stream = io.BytesIO(b'file bytes')
            built.append(stream)
            return stream

        def consuming_transport(stream):
            data = stream.read()
            self.assertEqual(data, b'file bytes')
            return LIMITED if len(built) == 1 else SENT

        clock = Clock()
        decision = policy.send(make_request, consuming_transport,
                               policy.FloodGate(clock, clock.sleep), 'chat:1')
        self.assertEqual(decision.action, policy.DONE)
        self.assertEqual(len(built), 2)
        self.assertEqual(clock.slept, [7])

    def test_timeout_is_not_retried(self):
        decision, seen, _ = self.run_send([TimeoutError('read timed out'), SENT])
        self.assertEqual(decision.action, policy.UNKNOWN)
        self.assertEqual(len(seen), 1)

    def test_server_error_is_not_retried(self):
        decision, seen, _ = self.run_send([(502, 'bad gateway'), SENT])
        self.assertEqual(decision.action, policy.UNKNOWN)
        self.assertEqual(len(seen), 1)

    def test_any_transport_exception_is_unknown(self):
        for error in (ValueError('library timeout'), KeyError('incomplete read')):
            decision, seen, _ = self.run_send([error, SENT])
            self.assertEqual(decision.action, policy.UNKNOWN)
            self.assertEqual(len(seen), 1)

    def test_failed_request_build_is_raised_and_sends_nothing(self):
        def make_request():
            raise FileNotFoundError('photo.jpg')

        with self.assertRaises(FileNotFoundError):
            self.run_send([SENT], make_request=make_request)

    def test_long_pause_returns_to_the_caller_with_the_server_wait(self):
        limited = (429, body(ok=False, parameters={'retry_after': 7200}))
        decision, seen, clock = self.run_send([limited, SENT])
        self.assertEqual((decision.action, decision.wait), (policy.FAIL, 7200))
        self.assertEqual(len(seen), 1)
        self.assertEqual(clock.slept, [])

    def test_gives_up_after_max_attempts(self):
        decision, seen, clock = self.run_send([LIMITED, LIMITED], max_attempts=2)
        self.assertEqual(decision.action, policy.FAIL)
        self.assertEqual(len(seen), 2)
        self.assertEqual(clock.slept, [7])

    def test_bad_max_attempts(self):
        for value in (0, -1, '3', True):
            with self.assertRaises(ValueError):
                self.run_send([SENT], max_attempts=value)

if __name__ == '__main__':
    unittest.main()
```

## File: README.md
upstream: https://github.com/serejaris/telegram-skills/blob/main/README.md

````text
# Telegram Skills for AI Agents

**Telegram skills** are [Agent Skills](https://agentskills.io) (folders with a `SKILL.md` file) that teach an AI agent how to work with Telegram. This library gives Claude Code, Codex CLI, Cursor and any other compatible agent a Telegram skill for each job: sending Rich Messages (tables, galleries, maps, collapsible sections), streaming AI replies, building interactive HTML widgets, running polls, publishing sticker packs, writing channel digests, launching and securing Mini Apps, and selling for Stars from any bot. Every skill calls the Bot API over raw HTTP, so no bot framework is required.

Guide (in Russian): [Telegram skills for Claude Code and Codex](https://sereja.tech/blog/telegram-skills-claude-code/).

## Skills

| Skill | What it does |
|---|---|
| [`tg-rich-messages`](skills/tg-rich-messages/SKILL.md) | Core reference: markup, outgoing block JSON, media bindings and uploads, preflight, limits, raw HTTP sending |
| [`tg-markdown-to-rich`](skills/tg-markdown-to-rich/SKILL.md) | Convert Markdown into a rich message and bind `file_id`, URL, or uploaded media |
| [`tg-rich-streaming`](skills/tg-rich-streaming/SKILL.md) | Stream LLM output into a chat: plain and rich drafts, thinking block, stop button, mandatory finalization |
| [`tg-polls`](skills/tg-polls/SKILL.md) | Polls and quizzes from a bot or a user account: text + poll in one message via description, media, 12 options, all poll settings and limits, reading results |
| [`tg-rich-digest`](skills/tg-rich-digest/SKILL.md) | Digest and channel-article patterns: flat layout, preview + collapsed full version, media as evidence, preflight gate |
| [`tg-reply-rewrite`](skills/tg-reply-rewrite/SKILL.md) | Rewrite a raw agent reply for a non-engineer on a phone: what happened and how urgent, what it means, a ready sentence to send back, every fact unchanged |
| [`tg-operator-cards`](skills/tg-operator-cards/SKILL.md) | Cards a bot sends to its own operator about one event (payment, order, enrollment): outcome and person on the first line, one fact per line, warning in place of the normal line, decision footer, escaped dynamic text |
| [`tg-widgets`](skills/tg-widgets/SKILL.md) | Interactive HTML message widgets (HTML bubbles, `sendWidget`): how to write them by Telegram's docs, limits, input, state, which chats accept a widget in production |
| [`tg-sticker-pack`](skills/tg-sticker-pack/SKILL.md) | Static stickers from a meme frame or video: cutout, caption on top (WordArt, Impact, tags), offline format check, publishing through @Stickers from a user account or `createNewStickerSet` from a bot |
| [`tg-miniapp-launch-auth`](skills/tg-miniapp-launch-auth/SKILL.md) | Open a Mini App and trust its user: launch paths, `startapp`, `initData` by HMAC and Ed25519, version gating, origin protection, test environment |
| [`tg-miniapp-ui`](skills/tg-miniapp-ui/SKILL.md) | Build a Mini App interface: theme, safe areas, fullscreen, bottom buttons, haptics, performance, client bugs by platform |
| [`tg-stars-payments`](skills/tg-stars-payments/SKILL.md) | Sell digital goods for Stars from a bot or Mini App: invoices, pre-checkout, crediting by `telegram_payment_charge_id` with an atomic delivery claim, refunds, subscriptions, paid media, dated payout figures |
| [`tg-classic-messages`](skills/tg-classic-messages/SKILL.md) | Ordinary bot messages: limits, HTML and MarkdownV2 escaping, quotes, `date_time`, link previews, captions, albums, upload sizes, editing and deleting; when to choose rich instead |
| [`tg-capability-map`](skills/tg-capability-map/SKILL.md) | What a bot can do, what lives only in the client or MTProto, and what not to promise; every row dated with an address |
| [`tg-bot-ops`](skills/tg-bot-ops/SKILL.md) | Running a bot: webhook or polling, `allowed_updates`, secret token, 429 and `retry_after`, file retries, lost and poison updates, `t.me` outages, local server |

## Install

**Universal (recommended)**

```bash
npx skills add serejaris/telegram-skills

# Install a single skill
npx skills add serejaris/telegram-skills --skill tg-rich-messages
```

**Claude Code (native marketplace)**

```bash
/plugin marketplace add serejaris/telegram-skills
/plugin install telegram-skills@telegram-skills
```

**Codex CLI**

```bash
npx skills add serejaris/telegram-skills
# or manually: cp -r skills/* ~/.agents/skills/
# Inside a clone of this repo, skills are auto-discovered via .agents/skills/
```

**Manual copy**

```bash
# Claude Code
cp -r skills/* ~/.claude/skills/

# Codex CLI / other agents
cp -r skills/* ~/.agents/skills/

# or per-project
cp -r skills/* your-project/.claude/skills/
cp -r skills/* your-project/.agents/skills/
```

Then ask your agent — e.g. *"send this report to my Telegram channel as a rich message"*.

## Bot API versions

Bot API 10.1 (June 11, 2026) introduced [Rich Messages](https://core.telegram.org/bots/api#rich-message-formatting-options): bots can send document-grade structured messages and stream AI-generated replies with a native "thinking" block. Bot API 10.2 (July 14, 2026) added outgoing block JSON plus explicit media bindings, including Telegram `file_id`, HTTP URLs, and multipart uploads.

Bot API 10.3 (August 24, 2026) adds native rich-message button rows and compact tables. Styled inline keyboard buttons use `primary`, `success`, and `danger`. The dependency-free [Python UI helper](skills/tg-rich-messages/scripts/rich_ui.py) builds validated literal block payloads and native inline buttons; it performs no network calls. See [consumer integration](skills/tg-rich-messages/consumer-integration.md).

Polls (Bot API 9.1–10.1): up to 12 options, a 1024-char description with media, so a post and its poll fit in one message. See [`tg-polls`](skills/tg-polls/SKILL.md).

## Reference

- [`reference/rich-messages-spec.md`](reference/rich-messages-spec.md) — core extracted spec, limits and Bot API 10.3 UI additions
- Official: [Bot API docs](https://core.telegram.org/bots/api) · [changelog](https://core.telegram.org/bots/api-changelog) · demo bot [@RichTextDemoBot](https://t.me/RichTextDemoBot)

## License

MIT
````
