feat(commands): auto-register OnCommand handlers with Telegram

OnCommand now takes a description; the registered (command, description)
pairs are collected on the Bot (deduped by name) and published to
Telegram via SetMyCommands when the bot starts, so the client command
menu stays in sync with the handlers. Opt out with
Options.DisableCommandRegistration. Registration failure is logged, not
fatal. Update examples and docs for the new signature.

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

Author: ernado

bot.go

@@ -2,6 +2,8 @@ package botapi
 
 import (
 	"context"
+	"strings"
+	"sync"
 
 	"github.com/go-faster/errors"
 	"github.com/gotd/log"
@@ -33,6 +35,13 @@ type Bot struct {
 
 	onStart func(ctx context.Context)
 
+	// commands collects the (command, description) pairs registered through
+	// OnCommand so Run can publish them to Telegram. registerCommands gates the
+	// publish.
+	commandsMu       sync.Mutex
+	commands         []BotCommand
+	registerCommands bool
+
 	self *tg.User
 }
 
@@ -86,20 +95,58 @@ func New(token string, opt Options) (*Bot, error) {
 	*rawPlaceholder = *client.API()
 
 	b := &Bot{
-		token:   token,
-		log:     opt.Logger,
-		client:  client,
-		raw:     client.API(),
-		sender:  message.NewSender(client.API()),
-		peers:   pm,
-		gaps:    gaps,
-		disp:    disp,
-		onStart: opt.OnStart,
+		token:            token,
+		log:              opt.Logger,
+		client:           client,
+		raw:              client.API(),
+		sender:           message.NewSender(client.API()),
+		peers:            pm,
+		gaps:             gaps,
+		disp:             disp,
+		onStart:          opt.OnStart,
+		registerCommands: !opt.DisableCommandRegistration,
 	}
 	b.installHandlers()
 	return b, nil
 }
 
+// registerCommand records a command registered through OnCommand so Run can
+// publish the set to Telegram. Duplicate names keep their first description.
+func (b *Bot) registerCommand(name, description string) {
+	name = strings.TrimPrefix(name, "/")
+	if name == "" {
+		return
+	}
+	b.commandsMu.Lock()
+	defer b.commandsMu.Unlock()
+	for _, c := range b.commands {
+		if c.Command == name {
+			return
+		}
+	}
+	b.commands = append(b.commands, BotCommand{Command: name, Description: description})
+}
+
+// publishCommands reports the collected OnCommand set to Telegram (default
+// scope). Failures are logged, not fatal, since a bad description should not
+// stop the bot from serving.
+func (b *Bot) publishCommands(ctx context.Context) {
+	if !b.registerCommands {
+		return
+	}
+	b.commandsMu.Lock()
+	cmds := append([]BotCommand(nil), b.commands...)
+	b.commandsMu.Unlock()
+	if len(cmds) == 0 {
+		return
+	}
+	if err := b.SetMyCommands(ctx, cmds); err != nil {
+		b.log.Warn("Register bot commands", zap.Error(err))
+		return
+	}
+	b.log.Debug("Registered bot commands", zap.Int("count", len(cmds)))
+}
+
 // Run connects, authorizes as a bot, and blocks serving updates until ctx is
 // canceled or a fatal error occurs. Register handlers before calling Run.
 func (b *Bot) Run(ctx context.Context) error {
@@ -134,6 +181,7 @@ func (b *Bot) Run(ctx context.Context) error {
 					zap.Int64("id", me.ID),
 					zap.String("username", me.Username),
 				)
+				b.publishCommands(ctx)
 				if b.onStart != nil {
 					b.onStart(ctx)
 				}

commands_register_test.go

@@ -0,0 +1,46 @@
+package botapi
+
+import "testing"
+
+func TestOnCommandCollectsCommands(t *testing.T) {
+	b := newTestBot(t)
+	noop := func(*Context) error { return nil }
+
+	b.OnCommand("start", "Start the bot", noop)
+	b.OnCommand("/help", "Show help", noop) // leading slash is stripped
+	b.Group().OnCommand("ban", "Ban a user", noop)
+	b.OnCommand("start", "duplicate", noop) // dedup by name, keep first description
+
+	if len(b.commands) != 3 {
+		t.Fatalf("want 3 commands, got %d: %#v", len(b.commands), b.commands)
+	}
+	want := map[string]string{
+		"start": "Start the bot",
+		"help":  "Show help",
+		"ban":   "Ban a user",
+	}
+	for _, c := range b.commands {
+		if want[c.Command] != c.Description {
+			t.Fatalf("command %q: got %q, want %q", c.Command, c.Description, want[c.Command])
+		}
+	}
+}
+
+func TestRegisterCommandIgnoresEmpty(t *testing.T) {
+	b := newTestBot(t)
+	b.registerCommand("", "no name")
+	b.registerCommand("/", "slash only")
+	if len(b.commands) != 0 {
+		t.Fatalf("empty command names should be ignored, got %#v", b.commands)
+	}
+}
+
+func TestDisableCommandRegistration(t *testing.T) {
+	b, err := New("123:abc", Options{AppID: 1, AppHash: "h", DisableCommandRegistration: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if b.registerCommands {
+		t.Fatal("registerCommands should be false when disabled")
+	}
+}

doc.go

@@ -18,7 +18,7 @@
 //	if err != nil {
 //		return err
 //	}
-//	bot.OnCommand("start", func(c *botapi.Context) error {
+//	bot.OnCommand("start", "Start the bot", func(c *botapi.Context) error {
 //		_, err := c.Reply("hello")
 //		return err
 //	})

examples/buttons/main.go

@@ -54,7 +54,7 @@ func main() {
 
 	bot.Use(botapi.Recover(), botapi.Timeout(30*time.Second))
 
-	bot.OnCommand("menu", func(c *botapi.Context) error {
+	bot.OnCommand("menu", "Show the voting menu", func(c *botapi.Context) error {
 		_, err := c.Reply("How do you like this bot?", botapi.WithReplyMarkup(menu()))
 		return err
 	})

examples/echo/main.go

@@ -40,7 +40,7 @@ func main() {
 	// Middleware applies to every handler.
 	bot.Use(botapi.Recover(), botapi.Timeout(30*time.Second))
 
-	bot.OnCommand("start", func(c *botapi.Context) error {
+	bot.OnCommand("start", "Show the welcome message", func(c *botapi.Context) error {
 		_, err := c.Reply("Hi! Send me any text and I'll echo it back.")
 		return err
 	})

examples/media/main.go

@@ -48,13 +48,13 @@ func main() {
 
 	bot.Use(botapi.Recover(), botapi.Timeout(time.Minute), botapi.Logging())
 
-	bot.OnCommand("start", func(c *botapi.Context) error {
+	bot.OnCommand("start", "Show the welcome message", 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 {
+	bot.OnCommand("photo", "Send a sample photo", func(c *botapi.Context) error {
 		chat, ok := c.Chat()
 		if !ok {
 			return nil

group.go

@@ -8,7 +8,7 @@ package botapi
 //
 //	admin := bot.Group(ChatTypeIs(ChatTypeSupergroup))
 //	admin.Use(Recover())
-//	admin.OnCommand("ban", banHandler)
+//	admin.OnCommand("ban", "Ban a user", banHandler)
 type Group struct {
 	bot   *Bot
 	preds []Predicate
@@ -46,6 +46,7 @@ func (g *Group) OnCallbackQuery(h Handler, predicates ...Predicate) {
 }
 
 // OnCommand registers a command handler in the group.
-func (g *Group) OnCommand(name string, h Handler, predicates ...Predicate) {
+func (g *Group) OnCommand(name, description string, h Handler, predicates ...Predicate) {
+	g.bot.registerCommand(name, description)
 	g.OnMessage(h, prepend(Command(name), predicates)...)
 }

options.go

@@ -60,6 +60,11 @@ type Options struct {
 	// RequestBurst is the token-bucket burst size for RequestsPerSecond. Defaults
 	// to 1 when RequestsPerSecond is set.
 	RequestBurst int
+
+	// DisableCommandRegistration stops Run from publishing the commands
+	// registered via OnCommand to Telegram (SetMyCommands, default scope). By
+	// default the bot's command menu is kept in sync with its OnCommand handlers.
+	DisableCommandRegistration bool
 }
 
 func (o *Options) setDefaults() {

predicates.go

@@ -139,7 +139,11 @@ func Or(predicates ...Predicate) Predicate {
 	}
 }
 
-// OnCommand registers a handler for the given bot command (e.g. "start").
-func (b *Bot) OnCommand(name string, h Handler, predicates ...Predicate) {
+// OnCommand registers a handler for the given bot command (e.g. "start"). The
+// description is shown in the client's command menu; unless command
+// registration is disabled, Run publishes the registered commands to Telegram
+// via SetMyCommands.
+func (b *Bot) OnCommand(name, description string, h Handler, predicates ...Predicate) {
+	b.registerCommand(name, description)
 	b.OnMessage(h, prepend(Command(name), predicates)...)
 }