docs(examples): add media bot example

Demonstrate media handling: /photo sends a photo by URL, incoming photos
are echoed back by file_id (no re-upload), and incoming documents are
echoed back with metadata resolved via GetFile. Uses inline predicates
for photo/document messages.

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

Author: ernado

docs/roadmap.md

@@ -170,9 +170,9 @@ Deferred within Phase 5: payment answers
 - ☑ `pool.Pool` re-pointed at public `Bot` (`pool/`): lazy per-token start,
   shared startup for concurrent callers, per-token bbolt storage, idle GC
   (`RunGC`), `Kill`/`Close`.
-- ◐ Examples: `examples/echo` (handler + middleware), `examples/buttons`
-  (inline keyboards + callback queries), `examples/inline` (inline mode). Media
-  bot still to add.
+- ☑ Examples: `examples/echo` (handler + middleware), `examples/buttons`
+  (inline keyboards + callback queries), `examples/inline` (inline mode),
+  `examples/media` (send by URL, echo incoming media by file_id, `GetFile`).
 - ☑ Allocation tests on hot paths (`bench_test.go`): entity/markup/user
   conversion and `file_unique_id`, with `-benchmem`.
 - ☐ Conformance test against kept `botdoc` extractor (API-version drift guard)

examples/media/main.go

@@ -0,0 +1,111 @@
+// Command media is a bot built on github.com/gotd/botapi that demonstrates
+// sending and receiving media:
+//
+//   - /photo sends a photo by URL.
+//   - sending the bot a photo echoes it back by file_id (no re-upload).
+//   - sending the bot a document echoes it back and reports its size via
+//     GetFile.
+//
+// Run it with an MTProto app identity (https://my.telegram.org) and a BotFather
+// token:
+//
+//	APP_ID=12345 APP_HASH=abcdef BOT_TOKEN=123:abc go run ./examples/media
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"strconv"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/gotd/botapi"
+)
+
+// A small public domain image to send for /photo.
+const samplePhotoURL = "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
+
+func main() {
+	log, _ := zap.NewDevelopment()
+	defer func() { _ = log.Sync() }()
+
+	appID, err := strconv.Atoi(os.Getenv("APP_ID"))
+	if err != nil {
+		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
+	}
+
+	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
+		AppID:   appID,
+		AppHash: os.Getenv("APP_HASH"),
+		Logger:  log,
+	})
+	if err != nil {
+		log.Fatal("Create bot", zap.Error(err))
+	}
+
+	bot.Use(botapi.Recover(), botapi.Timeout(time.Minute))
+
+	bot.OnCommand("start", func(c *botapi.Context) error {
+		_, err := c.Reply("Send me a photo or a file and I'll send it back. Or try /photo.")
+		return err
+	})
+
+	// Send a photo by URL — Telegram fetches it server-side.
+	bot.OnCommand("photo", func(c *botapi.Context) error {
+		chat, ok := c.Chat()
+		if !ok {
+			return nil
+		}
+		_, err := c.Bot.SendPhoto(c, chat, botapi.FileURL(samplePhotoURL), "Here's a cat 🐈")
+		return err
+	})
+
+	// Echo incoming photos back by file_id (no download/re-upload round trip).
+	bot.OnMessage(func(c *botapi.Context) error {
+		photos := c.Message().Photo
+		largest := photos[len(photos)-1] // last size is the highest resolution
+		chat, _ := c.Chat()
+		_, err := c.Bot.SendPhoto(c, chat, botapi.FileID(largest.FileID),
+			fmt.Sprintf("%d×%d, file_unique_id=%s", largest.Width, largest.Height, largest.FileUniqueID))
+		return err
+	}, hasPhoto)
+
+	// Echo incoming documents back, reporting metadata resolved from the file_id.
+	bot.OnMessage(func(c *botapi.Context) error {
+		doc := c.Message().Document
+		chat, _ := c.Chat()
+
+		file, err := c.Bot.GetFile(c, doc.FileID)
+		if err != nil {
+			return err
+		}
+		caption := fmt.Sprintf("%s (%d bytes)\nfile_unique_id=%s",
+			doc.FileName, doc.FileSize, file.FileUniqueID)
+
+		_, err = c.Bot.SendDocument(c, chat, botapi.FileID(doc.FileID), caption)
+		return err
+	}, hasDocument)
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer cancel()
+
+	log.Info("Starting media bot")
+	if err := bot.Run(ctx); err != nil {
+		log.Fatal("Run", zap.Error(err))
+	}
+}
+
+// hasPhoto matches messages that carry a photo.
+func hasPhoto(u *botapi.Update) bool {
+	m := u.EffectiveMessage()
+	return m != nil && len(m.Photo) > 0
+}
+
+// hasDocument matches messages that carry a document.
+func hasDocument(u *botapi.Update) bool {
+	m := u.EffectiveMessage()
+	return m != nil && m.Document != nil
+}