How Telegram Bots Use Rich Text Formatting: Headers, Native Tables, LaTeX Math, Spoilers & Bot API 7.x Entities
Move beyond plain Markdown asterisks. Telegram Bot API unlocks nearly 100 formatting entities, enabling AI agents and automated services to transmit structured tables, multi-level headers, collapsible blockquotes, syntax-highlighted code, and mathematical formulas directly in chat threads.
data_object The MessageEntity Architecture: UTF-16 Code Unit Parsing
Telegram formats messages using an explicit array of MessageEntity objects. Rather than relying solely on fragile regex parsing or HTML tags that can fail on user-generated inputs, bots can transmit raw text coupled with byte-accurate offset and length coordinates.
Native Tables & Grids
Render clean financial balance sheets and system metrics with column-aligned cells. Eliminates the need for ugly monospace ASCII tables that overflow mobile screens.
Collapsible Blockquotes
Wrap lengthy stack traces, terms of service, or AI thought reasoning steps inside tap-to-expand collapsible quotes using the expandable_blockquote entity.
LaTeX & Formula Formatting
Format mathematical equations and academic notations cleanly. The client renders superscripts, subscripts, fractions, and Greek symbols natively.
terminal Interactive Sandbox: Live Entity Renderer vs. JSON Payload
Select an enterprise bot payload below to inspect the real-time visual output inside the Telegram chat bubble alongside the exact Bot API JSON schema sent to sendMessage.
📊 Production Node Cluster
| Node | Status | Load |
| us-east-1 | ACTIVE | 34% |
| eu-central-1 | ACTIVE | 58% |
sendMessage Payload
{
"chat_id": 982736154,
"text": "📊 Production Node Cluster | Active Fleet",
"entities": [
{
"type": "bold",
"offset": 0,
"length": 25
},
{
"type": "table",
"offset": 26,
"length": 68
}
]
}
terminal Production Code Pattern: aiogram 3.x with HTML & Entities
Safely format outbound bot messages with tables, collapsible blockquotes, and spoilers using modern Python frameworks.
compare_arrows Parsing Paradigms: MarkdownV2 vs. HTML vs. Raw Entities
Select the optimal parsing mode depending on whether your bot generates dynamic text or static templates.
| Parsing Mode | Pros | Cons / Gotchas | Recommended Use Case |
|---|---|---|---|
| Raw Entities Array | 100% immune to parse errors; zero character escaping required | Requires UTF-16 code unit offset calculations | AI Agents & Dynamic LLM Stream Output |
| HTML Parse Mode | Human-readable; supports <blockquote expandable> & <tg-spoiler> |
Must sanitize <, >, and & in dynamic inputs |
Standard Transactional & Alert Bots |
| MarkdownV2 | Compact syntax for bold and italics | Requires escaping 18 punctuation symbols (_ * [ ] ( ) ~ \ ` > # + - = | { } . !) |
Static Short Notifications |
help Frequently Asked Questions
Essential troubleshooting for bot developers implementing rich text formatting.
Telegram calculates offset and length using UTF-16 code units, not standard Python character counts (code points). Many emojis (such as 📊 or 🚀) consume 2 UTF-16 code units (a surrogate pair). In Python, calculate entity positions using len(text.encode('utf-16-le')) // 2 to prevent misaligned formatting.
In HTML mode, wrap the desired text block inside <blockquote expandable>Your text here</blockquote>. If submitting raw entities, use {"type": "expandable_blockquote", "offset": X, "length": Y}. The client automatically truncates long texts and displays a chevron arrow to expand.
Telegram permits up to 100 formatting entities per single message. If your payload exceeds 100 entities (such as massive tables or heavily annotated code snippets), the Telegram API returns a 400 Bad Request: too many entities error.
