feat(bot): background-send context (Bot.Background)

A handler's context is per-update and may be canceled (Timeout
middleware) when the handler returns, so it can't drive background work.
Add Bot.Background()/Context.Background() — a context tied to the bot's
run lifetime — for proactive sends to any chat from timers, queues or
goroutines. Returns an already-canceled context before Run/after stop.
Add Bot.Logger(); demo via the example's /remind, document in the guide,
note in the changelog.

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

Author: ernado

CHANGELOG.md

@@ -12,6 +12,9 @@ messages follow [Conventional Commits](https://www.conventionalcommits.org/).
 - **Rich messages** (Bot API 10.1) — `SendRichMessage`/`SendRichHTML`/
   `SendRichMarkdown` send structured page-block content built with
   `github.com/gotd/td/telegram/message/rich`.
+- **Background sends** — `Bot.Background()` / `Context.Background()` expose a
+  run-lifetime context for proactive sends to any chat from timers, queues or
+  goroutines, instead of the per-update handler context. Plus `Bot.Logger()`.
 
 ## [0.1.0] - 2026-06-14
 

background_test.go

@@ -0,0 +1,45 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+)
+
+func TestBackgroundContext(t *testing.T) {
+	b := newTestBot(t)
+
+	// Before Run, Background is already canceled so background sends fail fast.
+	if err := b.Background().Err(); err == nil {
+		t.Fatal("Background before Run should be canceled")
+	}
+
+	// While running, it returns the live run context.
+	ctx, cancel := context.WithCancel(context.Background())
+	b.setRunCtx(ctx)
+	if got := b.Background(); got != ctx {
+		t.Fatalf("Background should return the run context, got %v", got)
+	}
+	if b.Background().Err() != nil {
+		t.Fatal("live run context should not be canceled")
+	}
+
+	// Canceling the run context (bot stopping) cancels background work.
+	cancel()
+	if b.Background().Err() == nil {
+		t.Fatal("canceled run context should propagate")
+	}
+
+	// After Run returns, runCtx is cleared back to a canceled context.
+	b.setRunCtx(nil)
+	if b.Background().Err() == nil {
+		t.Fatal("Background after stop should be canceled")
+	}
+}
+
+func TestContextBackgroundDelegates(t *testing.T) {
+	b := newTestBot(t)
+	c := &Context{Bot: b, Update: &Update{}}
+	if c.Background() != b.Background() {
+		t.Fatal("Context.Background should delegate to Bot.Background")
+	}
+}

bot.go

@@ -42,6 +42,11 @@ type Bot struct {
 	commands         []BotCommand
 	registerCommands bool
 
+	// runMu guards runCtx, the bot's run-lifetime context, used for background
+	// (proactive) sends that must outlive a single update handler.
+	runMu  sync.Mutex
+	runCtx context.Context
+
 	self *tg.User
 }
 
@@ -151,6 +156,11 @@ func (b *Bot) publishCommands(ctx context.Context) {
 // canceled or a fatal error occurs. Register handlers before calling Run.
 func (b *Bot) Run(ctx context.Context) error {
 	return b.client.Run(ctx, func(ctx context.Context) error {
+		// Expose the connection-lifetime context for background sends, and clear
+		// it on shutdown so background work stops with the bot.
+		b.setRunCtx(ctx)
+		defer b.setRunCtx(nil)
+
 		status, err := b.client.Auth().Status(ctx)
 		if err != nil {
 			return errors.Wrap(err, "auth status")
@@ -207,3 +217,49 @@ func (b *Bot) Peers() *peers.Manager { return b.peers }
 
 // Self returns the bot's own user. It is nil until Run has authorized.
 func (b *Bot) Self() *tg.User { return b.self }
+
+// Logger returns the bot's zap logger.
+func (b *Bot) Logger() *zap.Logger { return b.log }
+
+func (b *Bot) setRunCtx(ctx context.Context) {
+	b.runMu.Lock()
+	b.runCtx = ctx
+	b.runMu.Unlock()
+}
+
+// Background returns a context tied to the bot's run lifetime, for proactive or
+// background sends that are not in response to an update — e.g. from a timer,
+// queue or goroutine. It is canceled when the bot stops.
+//
+// A handler's own context is per-update (and may carry a Timeout deadline), so
+// it must not be used for work that outlives the handler. Use Background
+// instead:
+//
+//	bot.OnCommand("remind", "Remind in a minute", func(c *botapi.Context) error {
+//		chat, _ := c.Chat()
+//		ctx := c.Bot.Background()
+//		go func() {
+//			time.Sleep(time.Minute)
+//			c.Bot.SendMessage(ctx, chat, "⏰ reminder")
+//		}()
+//		return nil
+//	})
+//
+// Before Run has connected (or after it has stopped) Background returns an
+// already-canceled context, so background sends fail fast rather than block.
+func (b *Bot) Background() context.Context {
+	b.runMu.Lock()
+	ctx := b.runCtx
+	b.runMu.Unlock()
+	if ctx == nil {
+		return canceledContext
+	}
+	return ctx
+}
+
+// canceledContext is returned by Background before the bot is running.
+var canceledContext = func() context.Context {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	return ctx
+}()

context.go

@@ -1,5 +1,7 @@
 package botapi
 
+import "context"
+
 // Message returns the message the update carries (new/edited message or channel
 // post), or nil.
 func (c *Context) Message() *Message { return c.Update.EffectiveMessage() }
@@ -60,6 +62,18 @@ func (c *Context) AnswerCallback(opts ...AnswerCallbackQueryOption) error {
 	return c.Bot.AnswerCallbackQuery(c, cq.ID, opts...)
 }
 
+// Background returns a context tied to the bot's run lifetime, for sends that
+// must outlive this handler (a timer, queue or goroutine). The handler's own
+// context is per-update and may be canceled (e.g. by Timeout middleware) as soon
+// as the handler returns, so do not capture it for background work.
+//
+// Send messages to any chat in the background with Bot.SendMessage and this
+// context:
+//
+//	ctx := c.Background()
+//	go func() { c.Bot.SendMessage(ctx, botapi.ID(other), "hi") }()
+func (c *Context) Background() context.Context { return c.Bot.Background() }
+
 // AnswerInline answers the update's inline query with the given results. It is
 // an error to call it when the update is not an inline query.
 func (c *Context) AnswerInline(results []InlineQueryResult, opts ...AnswerInlineQueryOption) error {

docs/guide.md

@@ -199,6 +199,31 @@ bot.OnInlineQuery(handler)
 > Updates for the bot's own outgoing messages are filtered out (the HTTP Bot API
 > never delivers them), so reply handlers won't answer themselves.
 
+### Sending in the background
+
+A handler's context is **per-update** — the `Timeout` middleware may give it a
+deadline, and it is canceled once the handler returns. Do not capture it for
+work that outlives the handler. For proactive sends (a timer, a queue, a
+goroutine) to any chat, use `Bot.Background()` (or `Context.Background()`), a
+context tied to the bot's run lifetime:
+
+```go
+bot.OnCommand("remind", "Remind me", func(c *botapi.Context) error {
+	chat, _ := c.Chat()
+	ctx := c.Background()
+	go func() {
+		time.Sleep(time.Minute)
+		c.Bot.SendMessage(ctx, chat, "⏰ reminder")
+	}()
+	return nil
+})
+```
+
+Outside any handler, keep the `*Bot` and call `bot.SendMessage(bot.Background(),
+botapi.ID(chatID), text)` from wherever you like once the bot is running.
+`Background` returns an already-canceled context before `Run` connects (and
+after it stops), so background sends fail fast instead of blocking.
+
 ## Predicates
 
 Every `On*` method accepts trailing `Predicate`s (`func(*Update) bool`); the

examples/advanced/main.go

@@ -211,6 +211,22 @@ func registerCommands(bot *botapi.Bot) {
 		return err
 	})
 
+	// Background send: reply now, then send again from a goroutine that outlives
+	// the handler. The handler's own context would be canceled on return, so use
+	// the bot's run-lifetime Background context.
+	bot.OnCommand("remind", "Send a reminder in 5 seconds (background)", func(c *botapi.Context) error {
+		chat, _ := c.Chat()
+		ctx := c.Background()
+		go func() {
+			time.Sleep(5 * time.Second)
+			if _, err := c.Bot.SendMessage(ctx, chat, "⏰ Here's your reminder!"); err != nil {
+				c.Bot.Logger().Warn("background reminder failed", zap.Error(err))
+			}
+		}()
+		_, err := c.Reply("OK, I'll remind you in 5 seconds.")
+		return err
+	})
+
 	bot.OnCommand("protect", "Send a message that can't be forwarded", func(c *botapi.Context) error {
 		_, err := c.Reply("🔒 This message has protected content.", botapi.ProtectContent())
 		return err
@@ -412,6 +428,7 @@ Commands:
 /forward — forward your message back
 /silent — silent message
 /protect — protected-content message
+/remind — background send after a delay
 
 Also try:
 • send me a <i>photo</i>, <i>document</i>, <i>sticker</i>, <i>location</i> or <i>contact</i>