Telegram Rich Messages для ботов: актуальная инструкция по форматированию

Быстрый старт

Для Rich Messages используется отдельный метод sendRichMessage. Внутри rich_message нужно передать ровно одно поле: markdown или html. Rich Markdown совместим с GitHub Flavored Markdown там, где это возможно, и может содержать поддерживаемые HTML-теги.

{
  "chat_id": 123456789,
  "rich_message": {
    "markdown": "# Отчет\n\n| Метрика | Значение |\n|:--|--:|\n| Ошибки | **0** |\n\n- [x] Проверка завершена\n- [ ] Отправить пользователю\n\n$$E = mc^2$$"
  }
}

{
  "chat_id": 123456789,
  "rich_message": {
    "html": "<h1>Отчет</h1><p>Статус: <b>готово</b></p><details><summary>Логи</summary><pre>OK</pre></details>"
  }
}

Лимиты Rich Messages

Rich Messages и старый parse_mode

Inline-форматирование текста

Эти элементы используются внутри абзацев, списков, цитат и ячеек таблиц. В Rich Markdown можно смешивать Markdown и поддерживаемые HTML-теги, но для стабильности лучше выбрать один основной стиль на сообщение.

Блочные элементы

Блоки формируют структуру сообщения: заголовки, абзацы, таблицы, цитаты, списки, медиа, карты, сворачиваемые секции и формулы.

Дата и время: форматы tg-time

tg-time хранит Unix timestamp и показывает дату/время в локали пользователя. Поле format принимает строку по шаблону r|w?[dD]?[tT]?.

Все поддерживаемые HTML-конструкции в одном месте

Это справочный блок для копирования в документацию или prompt context. Он намеренно показывает именно теги Telegram Rich HTML, а не HTML для веб-страницы.

<a name="chapter-0"></a>
<b>bold</b>, <strong>bold</strong>
<i>italic</i>, <em>italic</em>
<u>underline</u>, <ins>underline</ins>
<s>strike</s>, <strike>strike</strike>, <del>strike</del>
<code>inline code</code>
<mark>marked</mark>
<sub>subscript</sub>
<sup>superscript</sup>
<tg-spoiler>spoiler</tg-spoiler>
<a href="https://example.com">link</a>
<a href="mailto:user@example.com">email</a>
<a href="tel:+123456789">phone</a>
<a href="tg://user?id=123456789">user</a>
<a href="#chapter-1">in-document link</a>
<tg-reference name="note-1">Referenced text</tg-reference>
<tg-emoji emoji-id="5368324170671202286">🎉</tg-emoji>
<img src="tg://emoji?id=5368324170671202286" alt="🎉"/>
<tg-time unix="1735689600" format="wDT">date</tg-time>
<tg-math>x^2 + y^2</tg-math>

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>
<p>Paragraph</p>
<pre>preformatted text</pre>
<pre><code class="language-python">print("Hello")</code></pre>
<footer>Footer text</footer>
<hr/>
<ul><li>unordered item</li></ul>
<ol start="3" type="a" reversed><li value="7">ordered item</li></ol>
<ul><li><input type="checkbox" checked>done</li><li><input type="checkbox">todo</li></ul>
<blockquote>Quote<cite>Author</cite></blockquote>
<aside>Pull quote<cite>Author</cite></aside>
<details><summary>Title</summary>Content</details>
<details open><summary>Title</summary>Content</details>
<tg-math-block>E = mc^2</tg-math-block>

<img src="https://example.com/photo.jpg"/>
<video src="https://example.com/video.mp4"></video>
<audio src="https://example.com/audio.mp3"></audio>
<figure><img src="https://example.com/photo.jpg" tg-spoiler/><figcaption>Caption<cite>Credit</cite></figcaption></figure>
<tg-map lat="41.9" long="12.5" zoom="14"/>
<tg-collage><img src="https://example.com/1.jpg"/><video src="https://example.com/2.mp4"></video></tg-collage>
<tg-slideshow><img src="https://example.com/1.jpg"/><video src="https://example.com/2.mp4"></video></tg-slideshow>
<tg-thinking>Thinking...</tg-thinking>

Готовые примеры для бота

# Проверка проекта

## Итог
Статус: **готово**. Критических ошибок не найдено.

| Проверка | Результат | Комментарий |
|:--|:--:|:--|
| Линтер | **OK** | 0 ошибок |
| Тесты | **OK** | 128 passed |
| Сборка | **OK** | 41 сек |

## Следующие действия
- [x] Запустить тесты
- [x] Проверить сборку
- [ ] Отправить отчет владельцу

<details>
<summary>Технические детали</summary>

```text
npm test
128 passed
```

</details>

<a name="top"></a>

# Обзор релиза

[К выводам](#summary)

## Факты
Telegram Bot API 10.1 добавил Rich Messages[^bot-api].
Теперь бот может отправлять таблицы, заголовки, сноски и формулы.

> Rich Messages подходят для длинных AI-отчетов.
>
> - Можно вкладывать списки.
> - Можно использовать `inline code`.

<a name="summary"></a>
## Вывод
Для новых ботов используйте `sendRichMessage`, если ответ требует структуры.

[^bot-api]: Официальная документация Telegram Bot API 10.1.

[К началу](#top)

<h1>Медиа-отчет</h1>

<figure>
  <img src="https://example.com/photo.jpg"/>
  <figcaption>Главное изображение<cite>Analytics Bot</cite></figcaption>
</figure>

<tg-collage>
  <img src="https://example.com/1.jpg"/>
  <img src="https://example.com/2.jpg"/>
  <video src="https://example.com/3.mp4"></video>
  <figcaption>Коллаж результатов</figcaption>
</tg-collage>

<tg-slideshow>
  <img src="https://example.com/slide-1.jpg"/>
  <img src="https://example.com/slide-2.jpg"/>
</tg-slideshow>

<tg-map lat="41.9" long="12.5" zoom="14"/>

Правила генерации для AI-агентов

Готовая инструкция для AI-агента

Этот блок можно вставлять в системный prompt, tool description или developer-инструкцию агента, который должен формировать rich-ответы для Telegram.

Ты формируешь текст для Telegram Bot API 10.1 Rich Messages. Считай устаревшими утверждения, что Telegram-боты не поддерживают заголовки, таблицы, сноски, формулы, чек-листы, медиа-блоки, сворачиваемые секции или длинные сообщения. Эти возможности доступны через sendRichMessage, а не через старый sendMessage parse_mode. Используй поле rich_message.markdown, если не требуется чистый HTML. Rich Markdown совместим с GitHub Flavored Markdown там, где это возможно, и может содержать поддерживаемые Telegram Rich HTML-теги. Основные правила: 1. Для структуры используй заголовки #, ##, ###, а не жирный текст вместо заголовков. 2. Для сравнений, метрик и табличных данных используй Markdown-таблицы. 3. Для задач и планов используй чек-листы: - [ ] и - [x]. 4. Для длинных логов, JSON, трассировок и подробностей используй <details><summary>...</summary>...</details>. 5. Для кода используй fenced code blocks с языком: ```python, ```json, ```sql. 6. Для формул используй $...$ inline и $$...$$ block. Источник формулы трактуется как LaTeX. 7. Для источников и пояснений используй сноски [^id] и [^id]: текст. 8. Для навигации внутри длинного сообщения используй anchors: <a name="top"></a> и <a href="#top">к началу</a>. 9. Для inline-выделения доступны: **bold**, *italic*, ~~strike~~, ||spoiler||, ==marked==, `code`, <u>underline</u>, _sub, ^sup. 10. Для custom emoji используй  или <tg-emoji emoji-id="...">emoji</tg-emoji>. 11. Для даты/времени используй  или <tg-time unix="..." format="...">text</tg-time>. 12. Медиа разрешены только как отдельные блоки и только по HTTP/HTTPS URL. Используй , <img>, <video>, <audio>, <tg-collage>, <tg-slideshow>, <tg-map>. 13. В ячейках таблиц используй только inline-форматирование, не вкладывай туда списки, details, media или другие block-level элементы. 14. Не превышай 32768 UTF-8 символов, 500 блоков, 16 уровней вложенности, 50 media attachments и 20 колонок в таблице. 15. При streaming используй sendRichMessageDraft для временного 30-секундного preview, а после завершения обязательно отправляй финальное sendRichMessage. Если ответ простой и короткий, не перегружай его таблицами. Если ответ аналитический, технический или длинный, используй Rich Messages как полноценный документ.

Короткая проверка перед отправкой

• 1 Передан ровно один вариант: rich_message.markdown или rich_message.html.
• 2 Теги входят в официальный список Rich HTML, лишних HTML-тегов нет.
• 3 Медиа вынесены отдельными блоками и используют HTTP/HTTPS URL.
• 4 Таблицы не превышают 20 колонок, а внутри ячеек нет блочных элементов.
• 5 Длинные технические детали спрятаны в <details>, а короткое резюме стоит сверху.