Rich Messages: Complete Guide

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 object supports three interchangeable content modes:

Quick Start (HTML & Markdown Mode)

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

<?php
// ── Botlify Cloud .env — auto-injected, never hardcode secrets ──
$BOT_TOKEN     = getenv('BOT_TOKEN');     // Telegram bot token from @BotFather
$ADMIN_CHAT_ID = getenv('ADMIN_CHAT_ID'); // Your numeric admin Telegram user ID
$BOT_USERNAME  = getenv('BOT_USERNAME');  // Bot username without @

$resp = bot('sendRichMessage', [
    'chat_id'      => $chatId,
    'rich_message' => [
        'html' => '<h3>Weekly Report</h3><p>Users grew by <b>18%</b> this week.</p>',
    ],
]);

if ($resp['ok'] ?? false) {
    $richMessage = $resp['result']; // handle the sent RichMessage
}

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:

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

Block Catalog

Layout blocks (each page documents the exact fields):

Inline Text Styling (RichText)

Inside text blocks, the RichText family styles spans of text: bold, italic, underline, strikethrough, spoiler, code, subscript, superscript, datetime, custom emoji, math expressions, and auto-detected entities like URLs, mentions, hashtags, emails, phone numbers, bot commands, cashtags and bank card numbers.

Limits

Rich messages have dedicated size and content limits. See the official Rich Message Limits section, and the RichMessage / RichBlock reference pages for the returned objects.