---
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
"
"
"
"
Domain
Status
"
"
example.com
Available
"
"
foo.io
Taken
"
"
"
''
"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 | `