serejaris/telegram-skills / skills/tg-rich-messages
tg-rich-messages
VerifiedUse when sending structured or richly formatted messages from a Telegram bot — tables, section headings, collapsible blocks, photo galleries, maps, math formulas, audio, native styled buttons, bot UI cards, or streaming AI responses. Also use for understanding rich message types and limits when plain sendMessage with parse_mode HTML/Markdown is not sufficient.
tg-rich-messages
Sending requires network access to api.telegram.org and a 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.
Overview
Bot API 10.1 introduced Rich Messages. Bot API 10.2 (July 14, 2026) added direct
outgoing block JSON and explicit media bindings. Bot API 10.3 (August 24, 2026) added buttons,
compact tables, expandable quotations and document blocks. Rich messages are document-grade content
delivered directly in chat. Think Instant View articles — headings, tables, collage,
slideshow, map, math, collapsible blocks — but sent by a bot via sendRichMessage.
Use sendRichMessage instead of sendMessage when you need:
| Need | Mechanism |
|---|---|
| Section headings (h1–h6) | RichBlockSectionHeading |
| Tables with header rows / spanning cells | RichBlockTable |
| Collapsible sections | RichBlockDetails |
| Photo grid or slide deck | RichBlockCollage / RichBlockSlideshow |
| Embedded map | RichBlockMap |
| LaTeX math (inline or block) | RichTextMathematicalExpression / RichBlockMathematicalExpression |
| Streaming AI reply with "Thinking…" block | sendRichMessageDraft + RichBlockThinking |
| Footnotes / anchor links | RichTextReference / RichTextAnchorLink |
Stay on classic sendMessage when:
| Need | Why classic wins |
|---|---|
| Bold, italic, code, spoiler and links only | parse_mode: HTML covers it |
| Link preview under the post, or a chosen preview URL | sendRichMessage and InputRichMessage have no link_preview_options |
| Custom emoji in a bot's channel post | The docs allow them in private, group and supergroup chats, or for bots with a Fragment username; see Custom emoji |
| A message you will edit, with custom emoji | Rich edits can lose them; see Known bugs |
Bot UI composition (10.3)
Use the network-free Python helper for deterministic heading, paragraph, pre, compact table, details and photo blocks with literal strings. It validates a narrow subset, not the complete Bot API. Photo uploads stay in the consumer's authorized transport. See consumer integration for the exact API, illustrated previews, provenance, send/edit lifecycle and local tests.
Inline keyboard styles: primary, success, danger; omit for app default. Product composition: at most one primary CTA per screen; neutral secondary navigation. Green is reserved for confirmed success or a desirable commit, red for genuinely destructive actions. Ordinary Back/Cancel, bonus offers and verification actions remain neutral. Start with heading → brief value → next action; move provider plumbing and limits to contextual About/limits views. Review actual mobile outcomes and user feedback before adding emphasis. RichMessageButton additionally accepts link only for callback buttons. Never put link on InlineKeyboardButton. Native rich button rows use type: "buttons", 1–8 buttons and optional align: left|center|right; these are documented in the reference and intentionally outside the helper subset.
For decision/inference bots, explain what the product does and why it helps with a concrete input → criteria → result sequence. Offer a free catalogue and case preview before an explicit paid/quota-consuming run; cached navigation should not silently repeat inference. Attribute source-backed cases as your observed experiment, an external project, or a synthetic teaching adaptation. Keep source links available and longer provenance in a closed details block. Show actual outputs and disclose missing values honestly. See the onboarding section in consumer integration.
Direct block text is literal RichText. Keep dynamic strings unescaped; HTML escaping belongs only to an HTML renderer. A native JSON code block is {"type":"pre","text":json_string,"language":"json"}. Table cells require align and valign; compact tables use is_compact: true.
Update an acknowledged screen with editMessageText.rich_message, exactly one of text and rich_message. Keep returned Bot API message IDs and check callback ownership/current-screen binding. There is no editRichMessage. Do not silently duplicate a message after an unknown delivery outcome.
Sending: InputRichMessage
sendRichMessage takes an InputRichMessage object in its rich_message field.
Choose exactly one content field:
| Field | When to use |
|---|---|
html | Rich HTML with Telegram-specific tags |
markdown | GitHub-Flavored Markdown + Telegram extensions |
blocks | Direct InputRichBlock[] JSON for deterministic programmatic composition |
Do not pass multiple content fields. With html or markdown, add optional media bindings
for uploaded files, Telegram file_id values, or HTTP URLs.
Optional fields on InputRichMessage:
| Field | Type | Purpose |
|---|---|---|
is_rtl | Boolean | Render message right-to-left |
skip_entity_detection | Boolean | Disable auto-detection of URLs, emails, mentions, etc. |
media | InputRichMessageMedia[] | Resolve tg://photo, tg://video, tg://document, and tg://audio references in markup |
Media bindings for HTML and Markdown
Reference media in markup:




Then bind each ID:
{
"markdown": "## Launch\n\n",
"media": [
{
"id": "cover",
"media": {"type": "photo", "media": "AgAC...file_id"}
}
]
}
Media IDs are 1–64 characters using only letters, digits, _, and -. The nested
InputMedia*.media accepts a Telegram file_id, an HTTP/HTTPS URL, or
attach://<part_name>. Use JSON for file_id and URLs. Use multipart/form-data for
attach:// uploads and provide a file part with the same name.
InputRichMessageMedia.media may be InputMediaAnimation, InputMediaAudio,
InputMediaDocument, InputMediaPhoto, InputMediaVideo, or InputMediaVoiceNote. Markup
exposes four reference schemes: photo, video, document, and audio; animation travels
through video, and voice note through audio.
Captions and player metadata
The caption comes from the markup, not from the binding — the title argument of the
Markdown image syntax (or <figcaption> in HTML):

InputMedia*.caption inside the binding is ignored. What the binding does carry is
player metadata, and for audio it is what turns a raw file into a labelled track in the
message:
{
"id": "live_answer",
"media": {
"type": "audio",
"media": "attach://live_answer_file",
"duration": 4,
"performer": "Grok Voice 2.0",
"title": "Answer: 323"
}
}
| Type | Metadata worth setting |
|---|---|
audio | duration, performer, title — shown in the inline player |
video | duration, width, height, thumbnail, supports_streaming, has_spoiler |
photo | has_spoiler |
Set duration even when Telegram can infer it: several short clips in one message render
as a consistent list only when every one of them reports its length.
Preflight: validate bindings before sending
Telegram reports a bad binding as one opaque Bad Request. Validate locally first and the
failure names the offending id. Four checks, all cheap:
- Every
tg://…?id=Xin markup has a binding. Missing → the media silently never renders or the call fails. - Every binding is referenced by the markup. An unused binding means an editing slip — a renamed id, a dropped paragraph. Telegram's behaviour here is unspecified; treat it as a build error of your own.
- The reference scheme matches the bound type.
tg://audio?id=Xacceptsaudioorvoice_note;tg://video?id=Xacceptsvideooranimation;tg://photo?id=Xacceptsphoto;tg://document?id=Xacceptsdocument. A mismatch is a definite error. - Every
attach://<name>has a matching file part, and the file exists on disk.
import re
REF = re.compile(r"tg://(photo|video|document|audio)\?id=([A-Za-z0-9_-]+)")
ACCEPTS = {"photo": {"photo"}, "video": {"video", "animation"}, "document": {"document"},
"audio": {"audio", "voice_note"}}
def check(markup: str, media: list[dict]) -> None:
bound = {item["id"]: item["media"]["type"] for item in media}
refs = set(REF.findall(markup))
referenced = {media_id for _, media_id in refs}
if missing := referenced - bound.keys():
raise ValueError(f"missing bindings: {sorted(missing)}")
if unused := bound.keys() - referenced:
raise ValueError(f"unused bindings: {sorted(unused)}")
for scheme, media_id in refs:
if bound[media_id] not in ACCEPTS[scheme]:
raise ValueError(f"{media_id}: tg://{scheme} cannot carry {bound[media_id]}")
Keep the file paths in a small manifest next to the payload — attachment name, path, MIME type — so the multipart step is a lookup rather than a second source of truth:
[
{"id": "cover", "attachment_name": "cover_file", "path": "cover.png", "mime_type": "image/png"}
]
Direct block JSON
Use blocks when code already has a structured document tree:
{
"blocks": [
{"type": "heading", "size": 2, "text": "Daily AI Brief"},
{"type": "paragraph", "text": ["One release matters today: ", {"type": "bold", "text": "Opus 5"}]},
{
"type": "photo",
"photo": {"type": "photo", "media": "AgAC...file_id"},
"caption": {"text": "Official launch image"}
}
]
}
Nested blocks use InputRichBlock. Media blocks embed InputMedia* directly. Put captions
in the outer block; captions inside nested InputMedia* are ignored.
Sending: HTTP calls
curl (HTML mode)
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendRichMessage" \
-H "Content-Type: application/json" \
-d '{
"chat_id": '"$CHAT_ID"',
"rich_message": {
"html": "<h2>Weekly Report</h2><p>Highlights from the past week.</p><table bordered><tr><th>Item</th><th>Value</th></tr><tr><td>Sales</td><td><b>142</b></td></tr></table>"
}
}'
Python (stdlib, HTML mode)
import json
import os
import urllib.request
TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
CHAT_ID = int(os.environ["CHAT_ID"])
payload = {
"chat_id": CHAT_ID,
"rich_message": {
"html": (
"<h2>Weekly Report</h2>"
"<p>Highlights from the past week.</p>"
"<table bordered>"
"<tr><th>Item</th><th>Value</th></tr>"
"<tr><td>Sales</td><td><b>142</b></td></tr>"
"</table>"
)
},
}
req = urllib.request.Request(
f"https://api.telegram.org/bot{TOKEN}/sendRichMessage",
data=json.dumps(payload).encode(),
headers={"Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(req) as resp:
result = json.load(resp)
Python (stdlib, Markdown mode)
payload = {
"chat_id": CHAT_ID,
"rich_message": {
"markdown": (
"## Weekly Report\n\n"
"Highlights from the past week.\n\n"
"| Item | Value |\n"
"|------|-------|\n"
"| Sales | **142** |\n"
)
},
}
See examples.md for more complete examples including streaming drafts,
collages, details blocks, and a full multipart upload.
Delivery outcomes: what a failed call actually means
A rich message with uploads is a large multipart request, so the interesting failures are not validation errors — they are the ones where you do not know whether the message went out. Split the response three ways:
| Response | Meaning | Correct reaction |
|---|---|---|
ok: true | Delivered | Store message_id — it is the handle for later editMessageText |
HTTP 4xx with ok: false | Definite failure, nothing was posted | Fix the payload and resend |
| HTTP 429 or 5xx, or a transport timeout | Unknown — the message may already be in the channel | Do not blind-retry |
The third row is the one that bites. Retrying a timed-out sendRichMessage is how a channel
gets the same article twice, and there is no dedup on Telegram's side. Mark the send as
unresolved instead, and require a human (or a lookup of the channel's last message) to
decide before anything is sent again. If you retry automatically anywhere, retry only calls
that failed with a definite 4xx.
Block types — quick reference
Structural blocks
| Type string | HTML tag | Purpose | Key fields |
|---|---|---|---|
paragraph | <p> | Text paragraph | text: RichText |
heading | <h1>–<h6> | Section heading | text, size: 1–6 (1 = largest) |
pre | <pre> | Preformatted / code block | text, language?: string |
footer | <footer> | Footer text | text: RichText |
divider | <hr/> | Horizontal rule | (no content fields) |
anchor | <a name="..."> | Named anchor point | name: string |
mathematical_expression | <tg-math-block> | Block LaTeX formula | expression: string |
list | <ul> / <ol> | Ordered or unordered list | items: RichBlockListItem[] |
blockquote | <blockquote> | Block quotation | blocks: RichBlock[], credit?: RichText |
expandable_blockquote | <blockquote expandable> | Collapsible quotation (10.3) | text: RichText, credit?: RichText |
pullquote | <aside> | Centered pull quote | text, credit?: RichText |
details | <details> | Collapsible section | summary: RichText, blocks: RichBlock[], is_open?: true |
table | <table> | Data table | cells: RichBlockTableCell[][], is_bordered?, is_striped?, is_compact?, caption?: RichText |
buttons | <tg-button-row> | One row of buttons (10.3) | buttons: RichMessageButton[], align? |
map | <tg-map> | Static embedded map | location: Location, zoom: 0–24, width, height, caption? |
collage | <tg-collage> | Photo/video grid | blocks: RichBlock[], caption?: RichBlockCaption |
slideshow | <tg-slideshow> | Swipeable photo/video deck | blocks: RichBlock[], caption?: RichBlockCaption |
photo | <img> | Photo block | photo: PhotoSize[], has_spoiler?: true, caption? |
video | <video> | Video block | video: Video, has_spoiler?: true, caption? |
animation | <video> (gif) | Animation / GIF block | animation: Animation, has_spoiler?: true, caption? |
audio | <audio> (mp3) | Audio / music block | audio: Audio, caption? |
voice_note | <audio> (ogg) | Voice message block | voice_note: Voice, caption? |
document | <tg-document> | General file block (10.3) | document: Document, caption? |
thinking | <tg-thinking> | "Thinking…" placeholder (draft only) | text: RichText |
thinkingis only valid insendRichMessageDraft. It cannot appear insendRichMessageand is never stored in a Message.
Inline text types (RichText)
| Type string | HTML tag | Purpose | Extra fields |
|---|---|---|---|
bold | <b> | Bold | text |
italic | <i> | Italic | text |
underline | <u> | Underline | text |
strikethrough | <s> | Strikethrough | text |
spoiler | <tg-spoiler> | Hidden spoiler text | text |
marked | <mark> | Highlight | text |
code | <code> | Inline monospace | text |
subscript | <sub> | Subscript | text |
superscript | <sup> | Superscript | text |
custom_emoji | <tg-emoji> | Custom emoji | custom_emoji_id, alternative_text |
mathematical_expression | <tg-math> | Inline LaTeX | expression: string |
date_time | <tg-time> | Formatted timestamp | text, unix_time: int, date_time_format: string |
text_mention | <a href="tg://user?id=..."> | User mention by ID | text, user: User |
mention | auto-detected | Username mention | text, username: string |
url | <a href="https://..."> | URL link | text, url: string |
email_address | <a href="mailto:..."> | Email link | text, email_address: string |
phone_number | <a href="tel:..."> | Phone link | text, phone_number: string |
bank_card_number | auto-detected | Bank card highlight | text, bank_card_number: string |
hashtag | auto-detected | Hashtag | text, hashtag: string |
cashtag | auto-detected | Cashtag | text, cashtag: string |
bot_command | auto-detected | Bot command | text, bot_command: string |
anchor | <a name="..."> (inline) | Inline anchor point | name: string |
anchor_link | <a href="#..."> | Link to anchor | text, anchor_name: string (empty = top) |
reference | <tg-reference name="..."> | Footnote definition | text, name: string |
reference_link | <a href="#..."> (ref) | Link to footnote | text, reference_name: string |
Markdown quick syntax
**bold** *italic* __bold__ _italic_
~~strikethrough~~ `code` ==marked== ||spoiler||
[Link text](https://example.com)
[Email](mailto:user@example.com)
[Phone](tel:+1234567890)
[Mention user](tg://user?id=123456789)


$inline LaTeX formula$
$$block LaTeX formula$$
# H1 ## H2 ... ###### H6
```python
code block with language
--- (divider)
- unordered item 1. ordered item
- task - [x] done task
blockquote line
Image # photo block Image # with caption Image # video block Image # audio block Image # voice note Image # animation
| Col 1 | Col 2 |
|---|---|
| left | right |
Text[^fn1]. [^fn1]: Footnote text.
Limits & traps
| Limit | Value |
|---|---|
| Max UTF-8 characters, including custom emoji alternative text and formula source | 32 768 |
| Max blocks, including nested blocks, list items, table rows, quotation and details blocks | 500 |
| Max levels of nested formatting and blocks | 16 |
| Max media attachments in total | 50 |
| Max table columns | 20 |
Buttons in one buttons block | 1–8 |
| Map zoom range | 0–24 |
Map width + height, ratio | 10 000 in total, ratio at most 20 |
Critical constraints
Choose exactly one content representation. Use html, markdown, or blocks.
Markup media has two source paths.
- Media must be specified as separate blocks, not inline in text.
- Direct HTTP/HTTPS media URLs work without
media. tg://photo?id=,tg://video?id=,tg://document?id=, andtg://audio?id=require a matching entry inmedia.- Each bound
InputMedia*.mediaacceptsfile_id, HTTP/HTTPS URL, or multipartattach://. - Direct URL media type is inferred from MIME type and URL extension. Bound media type comes
from the nested
InputMedia*object.
Table cells: inline formatting only.
No blocks (<p>, <ul>, <img>, etc.) inside <td> / <th>. Only inline tags.
RichBlockThinking is draft-only.
Can only appear in sendRichMessageDraft. Never in sendRichMessage. Never stored in a
Message object.
sendRichMessageDraft is private-chat only.
chat_id must be an Integer. @username strings are not accepted.
editMessageText: text and rich_message are mutually exclusive.
Pass exactly one. Sending both (or neither) is an error.
Map is static, no markers.
RichBlockMap renders a static tile at the given location and zoom level. No pins,
no interactivity.
Block count includes nesting.
The 500-block limit counts every RichBlockListItem, every table row, every block inside
blockquote / details. Deep nesting exhausts the budget fast.
Collage and slideshow accept both photos and videos.
blocks can mix photo and video blocks. Both may also be placed inside a details
block as collapsible media.
No link preview control.
sendRichMessage and InputRichMessage have no link_preview_options.
Custom emoji
The formatting rules allow custom emoji for bots that purchased additional usernames on Fragment, or in messages the bot sends directly to private, group and supergroup chats when its owner has Telegram Premium. Channels aren't named in the second case. Without a Fragment username, plan a channel post without custom emoji. Rich messages from a bot to a channel with custom emoji were not tested live for this skill.
Inline, guest and Web App results
InputRichMessageContent carries a rich message as a result of an inline query, a guest query
or a Web App query. It has one field, rich_message. Only previously uploaded files may be used
in it, so bind media by file_id:
{
"type": "article",
"id": "report-1",
"title": "Weekly report",
"input_message_content": {
"rich_message": {"markdown": "## Weekly report\n\n",
"media": [{"id": "cover", "media": {"type": "photo", "media": "AgAC...file_id"}}]}
}
}
Known bugs
Practitioner reports, status checked on 2026-10-30. Details: reference.
- Custom emoji lost on edit.
editMessageTextwithrich_messagereturnsok: trueand drops custom emoji: tdlib #865 (2026-07-04), #904 in supergroups when the original isn't a reply (2026-09-28), #880 for inline messages in groups and channels (2026-07-30). All open. Check the edited message in a real client, or resend instead of editing. chosen_inline_resultwithoutinline_message_idwhen the result usesInputRichMessageContentwith rich buttons: tdlib #895 (2026-08-28, open). Take the id from the callback query of those buttons.
Common mistakes
| Mistake | Fix |
|---|---|
Passing an array directly as rich_message | Wrap it as {"blocks":[...]} |
Using tg://...id=cover without media | Add an InputRichMessageMedia with id: "cover" |
| Leaving a bound id that markup no longer references | Drop the binding — an unused one is an editing slip, not a no-op |
Binding voice_note behind tg://video?id= | Match the scheme: photo→photo, video→video/animation, document→document, audio→audio/voice_note |
Sending attach://cover in JSON only | Switch the request to multipart/form-data and add the cover file part |
| Nesting the multipart form fields as JSON objects | Every non-file field is a string: json.dumps(rich_message) in one form field |
Putting the caption in InputMedia*.caption of a binding | Captions come from markup — the image title argument or <figcaption> |
Shipping audio bindings without duration/title | The inline player shows an unlabelled blob; set the metadata on the binding |
Retrying a sendRichMessage that timed out | Outcome is unknown — retrying duplicates the post; resolve it before resending |
Putting an InputMedia* caption inside a direct media block | Put the caption on InputRichBlockPhoto / Video / Audio / Document |
Putting <img> or <video> inline in <p> | Move media to its own block, outside <p> |
Adding block elements inside <td> | Only inline tags inside table cells |
Using RichBlockThinking in sendRichMessage | thinking is valid only in sendRichMessageDraft |
Calling sendRichMessageDraft with @username | Use numeric chat_id (Integer) |
Sending text and rich_message together in editMessageText | Pass exactly one |
Forgetting to call sendRichMessage after streaming | Draft expires after 30 s — always finalize with full message |
| Assuming a narrower fixed map zoom range | Outgoing InputRichBlockMap.zoom is optional and ranges 0–24 |
Using skip_entity_detection for manual link formatting | Set it to true to prevent double-detection when you already mark up URLs manually |
Full spec
All types, all fields, all format details: ../../reference/rich-messages-spec.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |