> For the complete documentation index, see [llms.txt](https://prethink.gitbook.io/prtelegrambot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prethink.gitbook.io/prtelegrambot/rich-messages.md).

# Rich messages

Sending messages built from blocks — headings, lists, tables, quotations and media.

A rich message is a different kind of message from a formatted one. A formatted message is a single run of text with entities laid over it — bold here, a link there. A rich message is built from **blocks**: headings, paragraphs, lists, tables, quotations, dividers, embedded photos and video, collapsible details. Telegram lays them out.

Bot API 10.1 introduced them; 10.3 added buttons inside them, attached documents, expandable quotations and compact tables.

## Sending one

The framework sends a rich message the same way it sends any other, so every [`OptionMessage`](https://prethink.gitbook.io/prtelegrambot/api/classes/optionmessage.md) setting keeps working:

```csharp
using PRTelegramBot.Attributes;
using PRTelegramBot.Interfaces;
using PRTelegramBot.Services.Messages;

[ReplyMenuHandler("Report")]
public static async Task Report(IBotContext context)
{
    const string html = """
        <h1>Weekly report</h1>
        <p>Revenue is up <b>12%</b> on last week.</p>
        <ul>
            <li>New users: 1 204</li>
            <li>Churn: 0.8%</li>
        </ul>
        <blockquote>Growth held through the weekend.</blockquote>
        """;

    await MessageSender.SendRichMessage(context, html);
}
```

{% hint style="warning" %}
The HTML here is the **rich message dialect**, not the one `ParseMode.Html` accepts. `<h1>`, `<ul>` and `<table>` mean something in a rich message and nothing in a formatted one. The Bot API's rich message formatting options page has the tag list.

The framework passes the HTML through Telegram.Bot's rich-message converter, then Telegram parses the markup. PRTelegramBot does not validate it on the way out.
{% endhint %}

## Options

Everything a rich message can carry is mapped exactly as it is for an ordinary message: menus, reply parameters, thread id, protected content, silent delivery, business connection, message effect, paid broadcast, direct messages topic, suggested post parameters and the [ephemeral parameters](https://prethink.gitbook.io/prtelegrambot/ephemeral-messages.md).

{% hint style="warning" %}
Ephemeral parameters on a rich message carry the same conditions as anywhere else: without a callback query to answer, Telegram needs the bot to be an administrator of the chat. See [Ephemeral messages](https://prethink.gitbook.io/prtelegrambot/ephemeral-messages.md).
{% endhint %}

```csharp
var option = new OptionMessage
{
    MenuInlineKeyboardMarkup = keyboard,
    ProtectedContent = true,
    EphemeralMessageParameters = context.Update.GetUserId()
};

await MessageSender.SendRichMessage(context, html, option);
```

What has no counterpart here is `ParseMode`, `Entities` and `DisableWebPagePreview` — the blocks carry their own structure, so there is nothing for those to apply to.

## Building one by hand

When the content is assembled rather than authored, an overload takes an `InputRichMessage` directly:

```csharp
var rich = new InputRichMessage
{
    Blocks = new InputRichBlock[]
    {
        new InputRichBlockSectionHeading { Text = "Weekly report" },
        new InputRichBlockParagraph { Text = "Revenue is up 12% on last week." },
        new InputRichBlockDivider(),
    }
};

await MessageSender.SendRichMessage(context, rich);
```

There are 26 block types and around 30 text types in `Telegram.Bot.Types`, and the framework does not wrap them — they are used directly, exactly like every other Telegram.Bot type.

Starting with 1.1.2, Telegram.Bot also accepts HTML and block arrays through implicit conversions. A `RichText` becomes a paragraph block:

```csharp
using Telegram.Bot.Types;

InputRichMessage htmlMessage = "<h1>Weekly report</h1>";
RichText paragraph = "Revenue is up 12% on last week.";
InputRichMessage blockMessage = new InputRichBlock[]
{
    new InputRichBlockSectionHeading { Text = "Weekly report" },
    paragraph,
    new InputRichBlockDivider()
};

await MessageSender.SendRichMessage(context, htmlMessage);
await MessageSender.SendRichMessage(context, blockMessage);
```

The HTML conversion resolves the same `tg://...?file_id=...` media references as the framework's string overload.

## Reusing Telegram media

HTML can reference a file that is already stored by Telegram instead of uploading it again. Use the media kind and its `file_id` in the source:

```html
<img src="tg://photo?file_id=<file-id>"/>
```

The supported kinds are `photo`, `video`, `document` and `audio`. `MessageSender.SendRichMessage` turns this reference into the media attachment expected by Telegram.Bot.

## Replying with a rich quote

Set `ReplyToMessageId` to the original message ID and pass the excerpts through `QuoteRichTexts`. For example, a reply handler can reuse the text the user selected.

```csharp
if (context.Update.Message is { ReplyToMessage: { } original, Quote.RichTexts: { Length: > 0 } excerpts })
{
    var options = new OptionMessage
    {
        ReplyToMessageId = original.Id,
        QuoteRichTexts = excerpts,
    };

    await MessageSender.SendRichMessage(context, "<p>Here is the requested clarification.</p>", options);
}
```

When building the quote by hand, preserve the order and formatting of the excerpts. Telegram accepts up to 32 excerpts totaling at most 1024 characters. [Bot API ReplyParameters](https://core.telegram.org/bots/api#replyparameters).

## Receiving one

An incoming rich message raises `OnRichMessageHandle`, and `MessageType.RichMessage` identifies it. See [Message events](https://prethink.gitbook.io/prtelegrambot/events/message-events.md).

Round-tripping works: `msg.RichMessage.ToHtml()` produces these `file_id` references, and passing that HTML back to `SendRichMessage` resolves them again, so a message can be read, edited and sent on without uploading its media again.
