Tg Rich Messages

tg-rich-messages

Sending requires network access to api.telegram.org and a Telegram bot token.

Overview

Bot API 10.1 introduced Rich Messages. Bot API 10.2 (July 14, 2026) added direct outgoing block JSON and explicit media bindings. 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:

Plain sendMessage with parse_mode: HTML still covers bold/italic/code/spoiler/links for simple formatting. Move to sendRichMessage only when you need structural blocks.

Sending: InputRichMessage

sendRichMessage takes an InputRichMessage object in its rich_message field. Choose exactly one content field:

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:

Media bindings for HTML and Markdown

Reference media in markup:

![](tg://photo?id=cover)
![](tg://video?id=demo)
![](tg://audio?id=voice)

Then bind each ID:

{
  "markdown": "## Launch\n\n![](tg://photo?id=cover)",
  "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, InputMediaPhoto, InputMediaVideo, or InputMediaVoiceNote. Markup exposes three reference schemes: photo, video, 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):

![](tg://photo?id=cover "Release notes: the model shipped on July 29")

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"
  }
}

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:

1. Every tg://…?id=X in markup has a binding. Missing → the media silently never renders or the call fails.
2. 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.
3. The reference scheme matches the bound type. tg://audio?id=X accepts audio or voice_note; tg://video?id=X accepts video or animation; tg://photo?id=X accepts photo. A mismatch is a definite error.
4. Every attach://<name> has a matching file part, and the file exists on disk.

import re

REF = re.compile(r"tg://(photo|video|audio)\?id=([A-Za-z0-9_-]+)")
ACCEPTS = {"photo": {"photo"}, "video": {"video", "animation"}, "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:

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

thinking is only valid in sendRichMessageDraft. It cannot appear in sendRichMessage and is never stored in a Message.

Inline text types (RichText)

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)
![custom emoji](tg://emoji?id=5368324170671202286)
![timestamp label](tg://time?unix=1647531900&format=wDT)
$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

# photo block # with caption # video block # audio block # voice note # animation

Text[^fn1]. [^fn1]: Footnote text.

Limits & traps

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=, and tg://audio?id= require a matching entry in media.
• Each bound InputMedia*.media accepts file_id, HTTP/HTTPS URL, or multipart attach://.
• 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.

Common mistakes

Full spec

All types, all fields, all format details: ../../reference/rich-messages-spec.md