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.
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 themarkdownfield — spec explicitly allows HTML tags in Rich Markdown.
RichBlockThinkingis only valid insendRichMessageDraft. It is never stored in aMessage.
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>"
}
}
textandrich_messageare mutually exclusive ineditMessageText— use exactly one.
An edit through
rich_messagecan drop custom emoji while returningok: true: tdlib #865 (open, status checked 2026-10-30). Finalization throughsendRichMessageisn'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).
- Add
stopped_message_generationtoallowed_updates, if the bot sets that list. - Match the update to the running stream by
chat.id,message_thread_idanddraft_id. - Cancel the model call and stop sending drafts.
- To keep the partial text, pass
keep_on_stop: trueon the draft calls and send the text as a new message.keep_on_stopalone 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, §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.
createForumTopiccan succeed while the new topic answers "message thread not found" to every bot write andTOPIC_ID_INVALIDtodeleteForumTopic: tdlib #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 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:
- Send initial
sendMessagewith"⌛ Generating…"placeholder. - 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— full block & inline type reference../../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: 194k | 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: 194k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |