feat(rich): support Bot API 10.1 rich messages

Add SendRichMessage / SendRichHTML / SendRichMarkdown, sending structured
page-block content via gotd/td's message/rich package and the sender's
RichMessage builder. Demonstrate in the advanced example (/rich,
/richhtml), document in the guide, note in the changelog.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

CHANGELOG.md

@@ -7,6 +7,12 @@ messages follow [Conventional Commits](https://www.conventionalcommits.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **Rich messages** (Bot API 10.1) — `SendRichMessage`/`SendRichHTML`/
+  `SendRichMarkdown` send structured page-block content built with
+  `github.com/gotd/td/telegram/message/rich`.
+
 ## [0.1.0] - 2026-06-14
 
 `botapi` was rebuilt from a codegen-first OpenAPI/ogen project into a

docs/guide.md

@@ -101,6 +101,31 @@ bot.SendMessage(ctx, chat, "*bold* _italic_ ||spoiler||",
 	botapi.WithParseMode(botapi.ParseModeMarkdownV2))
 ```
 
+## Rich messages
+
+Beyond formatted text, Telegram supports **rich messages** (Bot API 10.1):
+structured content — headings, paragraphs, lists, tables, block quotes, media,
+math — as a tree of page blocks rather than a flat string with entity ranges.
+Build the content with `github.com/gotd/td/telegram/message/rich` and send it
+with `SendRichMessage`:
+
+```go
+import "github.com/gotd/td/telegram/message/rich"
+
+msg := rich.New(
+	rich.Heading1(rich.Plain("Title")),
+	rich.Paragraph(rich.Bold(rich.Plain("Hello"))),
+).Input()
+bot.SendRichMessage(ctx, chat, msg)
+```
+
+For a whole HTML or Markdown document (parsed server-side), use the shortcuts:
+
+```go
+bot.SendRichHTML(ctx, chat, "<h1>Title</h1><p>Body</p>")
+bot.SendRichMarkdown(ctx, chat, "# Title\n\nBody")
+```
+
 ## Keyboards
 
 `ReplyMarkup` is a sealed union: `*InlineKeyboardMarkup`,

examples/advanced/main.go

@@ -21,6 +21,8 @@ import (
 
 	"go.uber.org/zap"
 
+	"github.com/gotd/td/telegram/message/rich"
+
 	"github.com/gotd/botapi"
 )
 
@@ -88,6 +90,31 @@ func registerCommands(bot *botapi.Bot) {
 		return err
 	})
 
+	// A rich message (Bot API 10.1): structured page-block content built with
+	// the gotd/td rich package.
+	bot.OnCommand("rich", "Send a structured rich message", func(c *botapi.Context) error {
+		chat, _ := c.Chat()
+		msg := rich.New(
+			rich.Heading1(rich.Plain("Rich messages")),
+			rich.Paragraph(rich.Concat(
+				rich.Plain("They carry "),
+				rich.Bold(rich.Plain("headings")),
+				rich.Plain(", "),
+				rich.Italic(rich.Plain("paragraphs")),
+				rich.Plain(" and more — a tree of blocks, not a flat string."),
+			)),
+			rich.Preformatted(rich.Plain("bot.SendRichMessage(ctx, chat, msg)"), "go"),
+		).Input()
+		_, err := c.Bot.SendRichMessage(c, chat, msg)
+		return err
+	})
+
+	bot.OnCommand("richhtml", "Send a rich message from HTML", func(c *botapi.Context) error {
+		chat, _ := c.Chat()
+		_, err := c.Bot.SendRichHTML(c, chat, "<h1>From HTML</h1><p>Parsed by Telegram into a <b>rich</b> message.</p>")
+		return err
+	})
+
 	bot.OnCommand("keyboard", "Show an inline keyboard with callbacks", func(c *botapi.Context) error {
 		_, err := c.Reply("Pick one:", botapi.WithReplyMarkup(demoInlineKeyboard()))
 		return err
@@ -370,6 +397,8 @@ const helpText = `<b>Advanced demo bot</b>
 Commands:
 /html — HTML formatting
 /md — MarkdownV2 formatting
+/rich — structured rich message (page blocks)
+/richhtml — rich message from HTML
 /keyboard — inline keyboard + callbacks
 /removekbd — remove the reply keyboard
 /photo — send a photo by URL

rich.go

@@ -0,0 +1,55 @@
+package botapi
+
+import (
+	"context"
+
+	"github.com/gotd/td/telegram/message/rich"
+	"github.com/gotd/td/tg"
+)
+
+// SendRichMessage sends a rich message (Bot API 10.1): structured content —
+// headings, paragraphs, lists, tables, block quotes, media, math and more — as
+// a tree of page blocks rather than a flat string with entity ranges.
+//
+// Build the content with github.com/gotd/td/telegram/message/rich, for example:
+//
+//	msg := rich.New(
+//		rich.Heading1(rich.Plain("Title")),
+//		rich.Paragraph(rich.Bold(rich.Plain("Hello"))),
+//	).Input()
+//	bot.SendRichMessage(ctx, chat, msg)
+//
+// For whole-document HTML or Markdown, prefer SendRichHTML / SendRichMarkdown.
+// The usual SendOptions (reply, silent, protect, reply markup) apply.
+func (b *Bot) SendRichMessage(ctx context.Context, chat ChatID, msg tg.InputRichMessageClass, opts ...SendOption) (*Message, error) {
+	var cfg sendConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	peer, err := b.resolveInputPeer(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+
+	builder := &b.sender.To(peer).Builder
+	builder, err = b.applySendConfig(builder, cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := builder.RichMessage(ctx, msg)
+	return b.sentMessage(ctx, peer, resp, err)
+}
+
+// SendRichHTML sends a rich message whose content is the given HTML document,
+// parsed by Telegram's servers.
+func (b *Bot) SendRichHTML(ctx context.Context, chat ChatID, html string, opts ...SendOption) (*Message, error) {
+	return b.SendRichMessage(ctx, chat, rich.HTML(html), opts...)
+}
+
+// SendRichMarkdown sends a rich message whose content is the given Markdown
+// document, parsed by Telegram's servers.
+func (b *Bot) SendRichMarkdown(ctx context.Context, chat ChatID, markdown string, opts ...SendOption) (*Message, error) {
+	return b.SendRichMessage(ctx, chat, rich.Markdown(markdown), opts...)
+}