# Rich Messages: Complete Guide

> Build fully formatted Telegram messages with blocks, HTML or Markdown: InputRichMessage, the block catalog, inline RichText styling, media layouts and limits.

**Category:** Telegram Bot API — Types (A-Z)  
**URL:** https://docs.botlify.cloud/rich-messages-guide  
**Platform:** Botlify Cloud (https://botlify.cloud)  

---

**Rich Messages** are fully formatted Telegram messages built from *blocks* — paragraphs, headings, lists, tables, collages, slideshows, quotations, media and more. They go far beyond plain `parse_mode` text: one message can mix media, structured layout, and inline text styling, similar to an HTML page.

- Send them with sendRichMessage (drafts with sendRichMessageDraft).

- A sent rich message is returned as a RichMessage object containing its blocks.

- Rich messages can also be edited ephemerally with editEphemeralMessageText, editEphemeralMessageMedia and related methods.

## Two Ways to Build a Rich Message

The [InputRichMessage](/inputrichmessage) object supports three interchangeable content modes:

| Field | Type | Description |
| --- | --- | --- |
| blocks | Array of InputRichBlock | Structured content as a list of block objects — full control over layout |
| html | String | Content described with rich-message HTML formatting |
| markdown | String | Content described with rich-message Markdown formatting |
| media | Array of InputRichMessageMedia | Media used by tg://photo?id=, tg://video?id=, tg://document?id= and tg://audio?id= links |
| is_rtl | Boolean | Show the message right-to-left |
| skip_entity_detection | Boolean | Disable automatic detection of URLs, mentions, hashtags, etc. |

## Quick Start (HTML & Markdown Mode)

For simple rich content, pass an HTML or Markdown string directly — Telegram renders it into blocks automatically:

```php

```

## Structured Blocks Mode

For precise layout, compose the message from typed blocks. Every block carries a `type` field; each type is documented on its own page in the list below. A simple example with one text paragraph containing bold inline text:

```php
{
  "blocks": [
    {
      "type": "paragraph",
      "text": { "type": "bold", "text": "Hello from Botlify Cloud!" }
    }
  ]
}
```

## Block Catalog

Layout blocks (each page documents the exact fields):

| Group | Blocks |
| --- | --- |
| Text | RichBlockParagraph, RichBlockSectionHeading, RichBlockDivider, RichBlockFooter |
| Quotations | RichBlockBlockQuotation, RichBlockExpandableBlockQuotation, RichBlockPullQuotation, RichBlockThinking |
| Lists & Tables | RichBlockList, RichBlockListItem, RichBlockTable, RichBlockTableCell |
| Media Layouts | RichBlockCollage, RichBlockSlideshow, RichBlockPhoto, RichBlockVideo, RichBlockAudio, RichBlockVoiceNote, RichBlockDocument, RichBlockAnimation, RichBlockMap |
| Interactive | RichBlockButtons, RichMessageButton, RichBlockAnchor, RichBlockDetails |

## Inline Text Styling (RichText)

Inside text blocks, the [RichText](/richtext) family styles spans of text: [bold](/richtextbold), [italic](/richtextitalic), [underline](/richtextunderline), [strikethrough](/richtextstrikethrough), [spoiler](/richtextspoiler), [code](/richtextcode), [subscript](/richtextsubscript), [superscript](/richtextsuperscript), [datetime](/richtextdatetime), [custom emoji](/richtextcustomemoji), [math expressions](/richtextmathematicalexpression), and auto-detected entities like [URLs](/richtexturl), [mentions](/richtextmention), [hashtags](/richtexthashtag), [emails](/richtextemailaddress), [phone numbers](/richtextphonenumber), [bot commands](/richtextbotcommand), [cashtags](/richtextcashtag) and [bank card numbers](/richtextbankcardnumber).

## Limits

Rich messages have dedicated size and content limits. See the official [Rich Message Limits](https://core.telegram.org/bots/api#rich-message-limits) section, and the [RichMessage](/richmessage) / [RichBlock](/richblock) reference pages for the returned objects.

> [!TIP]
> **Botlify Cloud Runtime**
> Credentials are auto-injected in .env — always load them with getenv(): BOT_TOKEN, ADMIN_CHAT_ID, BOT_USERNAME. Main database: database.db (SQLite, WAL mode). Runtime errors: error.log. Quick test: send to $ADMIN_CHAT_ID. Full details: Runtime Reference.