Tg Rich Digest

tg-rich-digest

Send a digest or report as a single structured Telegram Rich Message (Bot API 10.2) — section headings, topic lists, collapsible long-tail, photo collage, map embed, and a footer — all in one document-grade message.

Overview

A digest is a structured document, not a wall of text. Rich Messages let you organize it with real headings, lists, collapsible sections, and embedded media — readable on any screen, no HTML page required.

This skill covers the digest/report pattern specifically. For the complete block reference see ../tg-rich-messages/SKILL.md. To convert an existing Markdown report see ../tg-markdown-to-rich/SKILL.md.

Anatomy of a Digest

Recommended block sequence:

[heading h2]   — digest title + date range
[paragraph]    — 1–3 sentence lead: what happened, key number
[heading h3]   — topic 1
[list]         — 3–7 bullet items for topic 1
[heading h3]   — topic 2
[list]         — ...
[details]      — "All links / Full list" — long-tail, closed by default
[divider]      — visual separator before footer
[collage]      — photo report (optional)
[map]          — event location (optional)
[footer]       — date, source, issue number

Each element below is shown as HTML markup, the string placed inside InputRichMessage.html. Bot API 10.2 also accepts InputRichMessage.blocks for code-built documents.

Note: When you receive the message back, Message.rich_message contains the parsed RichBlock JSON (e.g. {"type": "heading", ...}). That structure is receive-only — you cannot send it.

Layout choice: flat digest vs. preview + full version

The anatomy above is the flat layout: everything visible, <details> reserved for the long tail. It works for a short digest — a handful of bullets a reader scans in the feed.

It stops working once the digest becomes an article. A long rich message in a channel is rendered collapsed anyway, but Telegram decides where to cut, and the cut usually lands mid-sentence in the middle of your third section. The fix is to make the cut yourself:

[heading h1]   — the claim, as a headline
[paragraph]    — 2-3 short paragraphs: the fact, your own check, the consequence
[photo]        — cover image
[details]      — "Read the full version" — the ENTIRE article, closed by default

Everything below the lead lives inside one <details> block: sections, media, sources, sign-off. The reader sees a deliberate preview and one button; the feed shows a clean card instead of an arbitrary truncation.

<h1>Voice model ships with Russian audio-to-audio</h1>
<p>The vendor shipped <code>voice-think-fast-2.0</code> on July 29. First audio in 0.7 s, $0.08 per minute.</p>
<p>We tested Russian audio-to-audio: the model heard the question and answered <b>323</b>.</p>
<img src="tg://photo?id=cover"/>
<details><summary>Read the full version</summary>
  <h2>What shipped</h2>
  ...
</details>

Budget the preview. Roughly 500 visible characters total before <details>, with no single paragraph over ~220 — past that the feed truncates the preview itself and the whole point is lost. Count visible characters, not markup.

Two rules that are easy to get wrong:

• Media before <details> counts as part of the preview. One cover image, no more.
• Keep the sign-off inside <details>. Anything after the closing tag reads as a detached fragment in the feed.

Heading

<h2>Weekly Digest &mdash; Jun 9&ndash;15</h2>

<h1>–<h6> map to heading sizes 1–6. Use <h2> for the digest title, <h3> for topic sections.

Lead paragraph

<p>This week the community hit <b>1,200 members</b>. Three tools shipped, one hot thread ran 80+ replies.</p>

Topic section

<h3>Top Discussions</h3>
<ul>
  <li><a href="https://example.com/thread/42">LLM context limits &mdash; practical patterns</a> &mdash; 81 replies</li>
  <li><a href="https://example.com/thread/55">Prompt caching deep dive</a> &mdash; 80% cost reduction reported</li>
</ul>

For ordered lists use <ol> with optional start, type ("1", "a", "A", "i", "I"), and reversed attributes on <ol>, or value on individual <li>.

Details block — long-tail

Use <details> for content most readers skip: full link lists, raw stats, appendices. Omit open to collapse by default.

<details><summary>All links this week (9)</summary>
<ol>
  <li><a href="https://example.com/thread/42">LLM context limits &mdash; practical patterns</a></li>
  <li><a href="https://example.com/thread/55">Prompt caching deep dive</a></li>
  <li><a href="https://github.com/example/promptkit">promptkit v0.4 release notes</a></li>
</ol>
</details>

Add open attribute (<details open>) only for critical content that should be visible by default.

Divider

<hr/>

Photo collage

Public HTTP or HTTPS URLs can be used directly. For Telegram file_id values or uploads, use tg://photo?id=..., tg://video?id=..., or tg://audio?id=... plus InputRichMessage.media.

<tg-collage>
  <figure><img src="https://example.com/photos/meetup-1.jpg"/><figcaption>Berlin meetup · June 10<cite>Photo: @photo_credit</cite></figcaption></figure>
  <img src="https://example.com/photos/meetup-2.jpg"/>
  <img src="https://example.com/photos/meetup-3.jpg"/>
</tg-collage>

Mix <img> and <video src="https://..."> inside <tg-collage> freely. Wrap in <details> when photos are supplemental.

Map embed

<tg-map lat="52.5200" long="13.4050" zoom="15"/>

zoom must be 13–20.

Footer

<footer>AI Builders Community &mdash; Issue #24 &mdash; Week of June 9&ndash;15, 2026</footer>

Media Patterns

Media can use public HTTP/HTTPS URLs directly. Existing Telegram file_id values and new multipart uploads use explicit Bot API 10.2 media bindings:

{
  "html": "<h2>Daily</h2><img src=\"tg://photo?id=cover\"/>",
  "media": [
    {"id": "cover", "media": {"type": "photo", "media": "AgAC...file_id"}}
  ]
}

For a new upload, set media to attach://cover_file, send multipart/form-data, and attach the binary under the cover_file part name.

Media as evidence, not decoration

A collage at the end of a digest is a photo report. A screenshot placed directly under the claim it supports is evidence, and it is what makes a digest worth more than the links it cites. In the preview + full version layout the body carries the media:

<h2>What shipped</h2>
<p>The release notes list the model as generally available.</p>
<img src="tg://photo?id=release_source"/>
<h2>Our test</h2>
<p>We asked it in Russian. It answered correctly.</p>
<audio src="tg://audio?id=live_answer"></audio>

Rules that hold up in practice:

• One source screenshot per factual claim that a reader might otherwise have to take on trust — a release page, a pricing table, a dashboard.
• Audio and video belong in the body, next to the claim, not collected into a trailing block. A comparison of four voice samples reads as a table when the clips are interleaved with their numbers, and as noise when they are stacked at the end.
• Give every binding its metadata (duration, performer, title for audio) — see ../tg-rich-messages/SKILL.md.
• One message per edition. Rich messages hold up to 50 media bindings; a follow-up post with "here are the screenshots I forgot" splits the artifact and cannot be edited into the original.

Photo collage

Group multiple photos (and optionally videos) into a single tile layout. Use <figure> with <figcaption> and <cite> for attribution.

<tg-collage>
  <figure>
    <img src="https://example.com/photos/meetup-1.jpg"/>
    <figcaption>Photos from the June meetup<cite>Photo: @photographer_handle</cite></figcaption>
  </figure>
  <img src="https://example.com/photos/meetup-2.jpg"/>
  <video src="https://example.com/videos/highlight.mp4"></video>
</tg-collage>

Mix <img> and <video> freely inside <tg-collage>.

Slideshow — sequential media

Use <tg-slideshow> when order matters (tutorial steps, before/after, event sequence):

<tg-slideshow>
  <figure><img src="https://example.com/slides/step-1.jpg"/><figcaption>Step 1: initial setup</figcaption></figure>
  <figure><img src="https://example.com/slides/step-2.jpg"/><figcaption>Step 2: configure</figcaption></figure>
</tg-slideshow>

Collage inside details — expand to see photos

Wrap a collage in <details> when photos are supplemental and should not dominate the digest on first glance:

<details><summary>Expand to see photo report (6 photos)</summary>
<tg-collage>
  <figure><img src="https://example.com/photos/meetup-berlin-1.jpg"/><figcaption>Community meetup &mdash; Berlin &mdash; 2026-06-10</figcaption></figure>
  <img src="https://example.com/photos/meetup-berlin-2.jpg"/>
  <img src="https://example.com/photos/meetup-berlin-3.jpg"/>
</tg-collage>
</details>

Map embed — event location

One static location tile, no interactive markers. zoom must be 13–20.

<tg-map lat="52.5200" long="13.4050" zoom="15"/>

Length Budgeting

In the preview + full version layout one more budget applies, and it is the one that actually binds: ~500 visible characters before <details>, no paragraph over ~220. The API limits above are generous; the feed card is not.

Counting blocks

Every items entry in a list counts as one block. Every blocks entry inside details counts. Nested list items each count individually. A collage with 8 photos = 1 (collage) + 8 (photo) = 9 blocks.

Overflow strategy

When a digest is near limits, cut in this order:

1. Trim details content first. Move excess links to a follow-up message or external page.
2. Reduce list depth. Flatten nested lists to a single level.
3. Split into two messages. End message 1 with a divider + "Continued →" footer; open message 2 with a heading "(continued)".
4. Drop media last. Collage/slideshow consume both block budget and media budget — remove if text is the priority.

Pre-calculate block count before sending: count top-level blocks + sum of all nested arrays.

Preflight gate

A digest published on a schedule needs a check that runs without taste. Everything below is mechanically verifiable, and each one has a failure mode that only shows up after the post is live and uneditable:

Run it as a script with a non-zero exit code, before the send, on every edition. Splitting the report into blocking and fixable keeps it usable: a dead link blocks, a long paragraph is a warning.

Sending the Digest

Use sendRichMessage. Supply exactly one of html, markdown, or blocks inside InputRichMessage.

Minimal call (raw HTTP):

curl -s -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": $CHAT_ID,
    "rich_message": {
      "markdown": "## Weekly Digest\n\nLead paragraph.\n\n### Top Topics\n\n- Item one\n- Item two\n\n---\n\n<footer>Issue #1 · 2026-06-15</footer>"
    }
  }'

For channels pass chat_id as "@channelname". The bot must have permission to send the relevant media types if the digest includes photos or video.

Compatibility Note

Rich Message rendering on older Telegram clients is not documented by Telegram. Before sending to your full audience:

1. Test with sendRichMessage to a single private chat or a staging channel.
2. Check visually in both mobile and desktop clients.
3. Use the official demo bot @RichTextDemoBot to preview rendering.

Related Skills

• ../tg-rich-messages/SKILL.md — complete block and inline type reference
• ../tg-markdown-to-rich/SKILL.md — convert existing Markdown into a rich message
• ../../reference/rich-messages-spec.md — canonical API spec (Bot API 10.2)