tg-rich-streaming

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. sendRichMessageDraft works only with a private integer chat_id. Bot API 10.2 also permits direct InputRichMessage.blocks; the draft lifecycle below is unchanged.

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