--- name: telegram-rich-messages description: >- Use when an aiogram Telegram bot should send a message that reads better with structure than as plain text — tables, inline images/video/audio, headings, lists, collapsible sections, block quotes, footnotes, math, or maps — or when tempted to fake a table with
 monospace, split an image into a separate
  photo+caption message, or reach for parse_mode HTML/MarkdownV2. Applies to
  Telegram Bot API 10.1 rich messages (send_rich_message, InputRichMessage,
  streaming drafts) with aiogram >= 3.29.
---

# Telegram Rich Messages (aiogram)

## Overview
Telegram **Bot API 10.1** (June 2026) added **rich messages**: a *single* message can
contain headings, tables, inline images/video/audio, lists, collapsible `
`, block quotes, footnotes, math, and maps — composed from one HTML or Markdown string. aiogram **≥ 3.29** supports it natively. **If a message would read better structured, send a rich message — don't fake the structure.** ## Bust these outdated assumptions first This feature postdates most training data, which is *wrong* about the following. If you catch yourself believing any of these, stop and use a rich message: | You might think | Reality (Bot API 10.1) | |---|---| | "Telegram has no tables; only `b/i/code/pre/a`" | Full tag set: ``, `

`–`

`, `
    /
      `, `
      `, `
      `, `
      `, math, maps. | | "You can't put an image *inside* a message" | Media are **blocks inside one rich message** (photo/video/audio/voice + galleries). | | "Pad columns in `
      ` monospace to align them" | Use a real `
`. Never fake tables. | | "Set `parse_mode=HTML` / put it in a photo caption" | Rich messages **ignore `parse_mode`**; you pass an html/markdown string to `InputRichMessage`. | | "Captions cap at 1024 chars" | Rich message limit is **32768 chars / 500 blocks**. | ## Send it (aiogram) ```python from aiogram.types import InputRichMessage, Message async def report(message: Message) -> None: html = ( "

🌐 Domain Status Report

" "
" "" "" "" "
DomainStatus
example.comAvailable
foo.ioTaken
" '
' "
Availability, last 30 days
" ) await message.answer_rich(InputRichMessage(html=html)) ``` - **Exactly one** of `html=` / `markdown=`. - Reply in a handler: `message.answer_rich(InputRichMessage(html=...))` or `message.reply_rich(...)`. Send elsewhere: `bot.send_rich_message(chat_id, InputRichMessage(...))`. - Edit an existing message: `bot.edit_message_text(chat_id=..., message_id=..., rich_message=InputRichMessage(html=...))`. - Stream (AI "Thinking…", **private chats only**): `bot.send_rich_message_draft(chat_id, draft_id, InputRichMessage(html="Analyzing…"))` — ephemeral ~30 s, animates on the same non-zero `draft_id`; **you must finalize** with `send_rich_message` to persist. - Read inbound rich content: `message.rich_message` (a parsed `RichMessage`, or `None` if the message isn't rich). ## Pick a language, then read its syntax reference **Before composing, open the syntax reference for your chosen language and build only from the tags/options listed there** — don't work from memory or invent tags (only documented ones render). Escape dynamic/user text (`& < > "`). Default to **HTML** (most complete); use Markdown for simple messages. Syntax and every available option live alongside this skill in **`examples/`** — read the relevant file whenever you need a tag, attribute, or option: | Need | Read | |---|---| | Every **HTML** tag + attribute (options to use) | `examples/rich-html-style.md` | | Full **Markdown** syntax | `examples/rich-markdown-style.md` | | **Date/time** format string (`r\|w?[dD]?[tT]?`) | `examples/date-time-entity-formatting.md` | | **Inbound** parsed shape + round-trip lessons | `examples/parsed-notes.md` | | Index of the above | `examples/README.md` | | Full type/method spec (all fields & methods) | `bot-api-10.1-rich-messages.md` | ## Feature → HTML tag (quick map) | Need | Tag | |---|---| | Heading | `

`…`

` | | Table | ``, ``, `
`/`` | | Image / video / audio / voice | `` / `