serejaris/telegram-skills / skills/tg-rich-streaming
tg-rich-streaming
VerifiedUse when streaming LLM or AI-generated replies to Telegram in real time (ChatGPT-style progressive output in a bot), showing a model thinking indicator, or delivering token-by-token text as an animated rich message draft that finalizes into a permanent message.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| scripts/stream_demo.py | script | 5.1 KB |
SKILL.md
View on GitHub---
name: tg-rich-streaming
description: "Use when streaming LLM or AI-generated replies to Telegram in real time (ChatGPT-style progressive output in a bot), showing a model thinking indicator, or delivering token-by-token text as an animated rich message draft that finalizes into a permanent message."
license: MIT
---
# tg-rich-streaming
Stream AI-generated text into a Telegram private chat with native draft animation and a "thinking" indicator — the same UX as ChatGPT or Claude, directly inside the bot.
Sending requires network access to `api.telegram.org` and `TELEGRAM_BOT_TOKEN`.
Checked against the official docs on 2026-10-30: Bot API 10.3 (latest, August 24, 2026). Nothing here was run against a live bot.
| Method | Content | Since | Finalize with |
|---|---|---|---|
| `sendMessageDraft` | plain `text` 0–4096, `parse_mode` or `entities`; empty `text` shows a "Thinking…" placeholder | 9.3, all bots since 9.5 | `sendMessage` |
| `sendRichMessageDraft` | `InputRichMessage`, including `<tg-thinking>` | 10.1 | `sendRichMessage` |
Both work only with a private integer `chat_id`. Both take `draft_id`, `message_thread_id`,
`can_stop` and `keep_on_stop`, and both drafts live 30 seconds. Bot API 10.2 also permits direct
`InputRichMessage.blocks`; the draft lifecycle below is unchanged. A rich draft can't upload new
files or upload by URL, so media in a draft must already have a `file_id`.
## Core pattern
Four mandatory steps. Skip step 3 and the draft disappears after ~30 seconds.
### Step 1 — open draft with Thinking block
Send the first `sendRichMessageDraft` immediately after the LLM call starts.
`draft_id` is any non-zero integer you generate once per response; keep it for all updates.
`RichBlockThinking` signals the model is working.
```
POST /sendRichMessageDraft
{
"chat_id": <integer>, // private chat only — no @username
"draft_id": 42,
"rich_message": {
"markdown": "<tg-thinking>Thinking…</tg-thinking>"
}
}
```
> Rich HTML tags (like `<tg-thinking>`) are valid pass-through inside the `markdown` field — spec explicitly allows HTML tags in Rich Markdown.
> `RichBlockThinking` is **only** valid in `sendRichMessageDraft`. It is never stored in a `Message`.
### Step 2 — update draft as tokens arrive
Call `sendRichMessageDraft` again with the **same `draft_id`** each time you have enough new text. The client animates the transition.
**Throttle**: send at most once every 1–2 seconds. The draft is ephemeral (~30 s window) — keep sending updates or move to step 3 before the window closes.
Drop the Thinking block from the first update that contains real content.
```
# pseudocode — generic async LLM stream
draft_id = generate_nonzero_id()
accumulated = ""
last_sent = 0
send_draft(chat_id, draft_id, thinking_markdown()) # step 1
for chunk in llm.stream(prompt):
accumulated += chunk.text
now = time.monotonic()
if now - last_sent >= 1.5: # throttle
send_draft(chat_id, draft_id, accumulated)
last_sent = now
finalize(chat_id, accumulated) # step 3 — mandatory
```
### Step 3 — finalize with sendRichMessage (mandatory)
After the LLM stream ends, call `sendRichMessage`. This creates the **permanent** message. If you skip this, the draft vanishes.
```
POST /sendRichMessage
{
"chat_id": <integer>,
"rich_message": {
"markdown": "<full generated text>"
}
}
```
### Step 4 — edits after finalization
Use `editMessageText` with the `rich_message` parameter to update the permanent message later (corrections, appended content, etc.).
```
POST /editMessageText
{
"chat_id": <integer>,
"message_id": <id from step 3 response>,
"rich_message": {
"markdown": "<revised text>"
}
}
```
> `text` and `rich_message` are mutually exclusive in `editMessageText` — use exactly one.
> An edit through `rich_message` can drop custom emoji while returning `ok: true`: [tdlib #865](https://github.com/tdlib/telegram-bot-api/issues/865) (open, status checked 2026-10-30). Finalization through `sendRichMessage` isn't affected; this step and the group fallback are.
---
## Stop button (10.3)
Pass `can_stop: true` on every draft call to show a button that stops further drafts. When the
user presses it, the bot receives the `stopped_message_generation` update
(`MessageGenerationStopped`: `chat`, `message_thread_id`, `draft_id`).
1. Add `stopped_message_generation` to `allowed_updates`, if the bot sets that list.
2. Match the update to the running stream by `chat.id`, `message_thread_id` and `draft_id`.
3. Cancel the model call and stop sending drafts.
4. To keep the partial text, pass `keep_on_stop: true` on the draft calls and send the text as a
new message. `keep_on_stop` alone isn't persistence: the draft still disappears after a short
time or when the bot sends a message.
```
POST /sendMessageDraft
{
"chat_id": <integer>,
"draft_id": 42,
"text": "Partial answer so far",
"can_stop": true,
"keep_on_stop": true
}
```
---
## Topics in private chats
`message_thread_id` targets a topic when the bot has forum topic mode enabled in private chats.
`getMe` reports it in `has_topics_enabled`. Check two things before you turn it on:
- **Money.** Under the [Bot Developer Terms](https://telegram.org/tos/bot-developers), §6.2.6, all
Telegram Stars purchases in a bot with topics in private chats enabled carry a non-refundable
15% fee, withheld by Telegram while the option stays on. A bot that sells for Stars pays it on
every purchase.
- **Dead topics.** `createForumTopic` can succeed while the new topic answers
"message thread not found" to every bot write and `TOPIC_ID_INVALID` to `deleteForumTopic`:
[tdlib #905](https://github.com/tdlib/telegram-bot-api/issues/905) (practitioner report, filed
2026-09-29, open on 2026-10-30, three episodes across several hundred topics). Handle the failed first write
and create a replacement topic.
Whether streaming needs topics, the sources disagree. Terms §6.2.6 still ties "the streaming of
message drafts" to topics in private chats and the 15% fee; the
[Bot API 9.5 changelog](https://core.telegram.org/bots/api-changelog) allowed all bots to use
`sendMessageDraft`. Follow the changelog for the method, and read §6.2.6 before enabling topics on
a selling bot. Neither was tested live.
---
## Pitfalls
| Trap | What happens | Fix |
|---|---|---|
| Skipped `sendRichMessage` after stream ends | Draft disappears after ~30 s, no permanent message | Always call `sendRichMessage` with full text as last step |
| `chat_id` is a String or `@username` | `sendRichMessageDraft` returns error | Only Integer chat_id supported for drafts; fall back to `sendMessage` + `editMessageText` in groups/channels |
| Sending a draft update every token | Flood / rate limit, poor animation | Batch tokens, send at most every 1–2 s |
| `RichBlockThinking` in `sendRichMessage` | Not stored in Message; spec prohibits it | Remove Thinking block before finalization |
| Partial Markdown mid-stream | Unclosed `` ``` `` or `**` renders broken | Either send complete blocks only, or use raw text during streaming and apply Markdown only at finalization |
| 30-second window expires mid-stream | Draft gone | If stream is slow, send a keep-alive draft update (even unchanged text) before the window closes |
| Stream keeps running after the user pressed Stop | Tokens are spent, drafts keep coming | Handle `stopped_message_generation` and cancel the model call |
| `keep_on_stop` treated as saved text | The draft disappears after a short time | Send the partial text as a new message |
---
## Group / channel fallback
`sendRichMessageDraft` is private-chat only. For groups and channels:
1. Send initial `sendMessage` with `"⌛ Generating…"` placeholder.
2. Edit with `editMessageText` (rich_message) when done.
No real-time animation, but the final message is rich-formatted.
---
## Request reference
```
sendMessageDraft POST /bot<TOKEN>/sendMessageDraft
chat_id Integer required — private chat only
message_thread_id Integer optional
draft_id Integer required — non-zero; same id = animated update
text String optional — 0-4096; empty shows "Thinking…"
parse_mode String optional
entities Array of MessageEntity optional
can_stop Boolean optional — show the stop button
keep_on_stop Boolean optional — keep the draft briefly after stop
sendRichMessageDraft POST /bot<TOKEN>/sendRichMessageDraft
chat_id Integer required — private chat only
message_thread_id Integer optional
draft_id Integer required — non-zero; same id = animated update
rich_message InputRichMessage required
can_stop Boolean optional — show the stop button
keep_on_stop Boolean optional — keep the draft briefly after stop
sendRichMessage POST /bot<TOKEN>/sendRichMessage
chat_id Integer or String required
rich_message InputRichMessage required
→ returns Message (use .message_id for edits)
editMessageText POST /bot<TOKEN>/editMessageText
chat_id Integer or String
message_id Integer
rich_message InputRichMessage (mutually exclusive with "text")
```
`InputRichMessage` fields: exactly one of `html`, `markdown`, or `blocks`, optional `is_rtl`, optional `skip_entity_detection`.
---
## Related
- [`../tg-rich-messages/SKILL.md`](../tg-rich-messages/SKILL.md) — full block & inline type reference
- [`../../reference/rich-messages-spec.md`](../../reference/rich-messages-spec.md) — core Bot API 10.3 reference
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |