feat: expose raw MTProto message and add pp example

Add Message.Raw to reach the original tg.Message behind a Bot API
Message, set during conversion. Add Bot.GetMessage to fetch a message
by id (with raw populated), since replied-to messages are not carried
by the update. New examples/pp bot pretty-prints the replied-to MTProto
message via tdp.Format.

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

Author: ernado

convert.go

@@ -192,6 +192,7 @@ func (b *Bot) convertMessage(ctx context.Context, m *tg.Message) (*Message, erro
 		Date:                m.Date,
 		Chat:                chat,
 		HasProtectedContent: m.Noforwards,
+		raw:                 m,
 	}
 	if v, ok := m.GetEditDate(); ok {
 		r.EditDate = v

convert_message_test.go

@@ -21,6 +21,22 @@ func convMsg(t *testing.T, m *tg.Message) *Message {
 	return r
 }
 
+func TestConvertMessageExposesRaw(t *testing.T) {
+	m := &tg.Message{ID: 42, Message: "hi"}
+
+	m.PeerID = &tg.PeerUser{UserID: 10}
+
+	r := convMsg(t, m)
+	if r.Raw() != m {
+		t.Fatalf("Raw() = %p, want original %p", r.Raw(), m)
+	}
+
+	// Synthesized stubs (e.g. JSON-decoded messages) carry no raw message.
+	if (&Message{}).Raw() != nil {
+		t.Fatal("Raw() of a zero Message should be nil")
+	}
+}
+
 func TestConvertTextMessageFromUser(t *testing.T) {
 	m := &tg.Message{ID: 7, Message: "hello world"}
 

examples/pp/main.go

@@ -0,0 +1,96 @@
+// Command pp is a bot that pretty-prints the raw MTProto message behind any
+// Bot API message. Send it anything and it replies with the tdp.Format dump of
+// the underlying tg.Message, reachable through Message.Raw — useful for
+// inspecting fields the typed Bot API surface does not expose.
+//
+// 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/pp
+package main
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"strconv"
+	"time"
+
+	"github.com/gotd/log/logzap"
+	"github.com/gotd/td/tdp"
+	"go.uber.org/zap"
+
+	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
+)
+
+func main() {
+	log, _ := zap.NewProduction()
+	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))
+	}
+
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+
+	defer func() { _ = store.Close() }()
+
+	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
+		AppID:   appID,
+		AppHash: os.Getenv("APP_HASH"),
+		Logger:  logzap.New(log),
+		Storage: store,
+	})
+	if err != nil {
+		log.Fatal("Create bot", zap.Error(err))
+	}
+
+	bot.Use(botapi.Recover(), botapi.Timeout(30*time.Second))
+
+	bot.OnCommand("start", "Show the welcome message", func(c *botapi.Context) error {
+		_, err := c.Reply("Reply to any message with /pp to dump its raw MTProto message.")
+		return err
+	})
+
+	// /pp pretty-prints the MTProto message the command replies to. The replied
+	// message is not carried by the update, so it is fetched with Bot.GetMessage,
+	// whose raw tg.Message (via Message.Raw) is dumped with tdp.Format.
+	bot.OnCommand("pp", "Pretty-print the replied-to MTProto message", func(c *botapi.Context) error {
+		msg := c.Message()
+
+		reply := msg.ReplyToMessage
+		if reply == nil {
+			_, err := c.Reply("Reply to a message with /pp to dump it.")
+			return err
+		}
+
+		target, err := c.Bot.GetMessage(c, botapi.ID(msg.Chat.ID), reply.MessageID)
+		if err != nil {
+			_, replyErr := c.Reply("Could not fetch the replied message: " + err.Error())
+			if replyErr != nil {
+				return replyErr
+			}
+
+			return err
+		}
+
+		_, err = c.Reply(tdp.Format(target.Raw()))
+
+		return err
+	})
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer cancel()
+
+	log.Info("Starting pp bot")
+
+	if err := bot.Run(ctx); err != nil {
+		log.Fatal("Run", zap.Error(err))
+	}
+}

get_message.go

@@ -0,0 +1,58 @@
+package botapi
+
+import (
+	"context"
+
+	"github.com/gotd/td/telegram/peers"
+	"github.com/gotd/td/tg"
+)
+
+// GetMessage fetches a single message from chat by its id and converts it to a
+// Bot API Message. The returned Message exposes the original MTProto message
+// through Raw, so callers can reach fields the typed surface does not cover.
+//
+// It issues the channel- or user-appropriate getMessages call, so chat must be
+// a peer the bot can address (seen before or backed by stored peer data); a
+// send-only PeerRef is rejected.
+func (b *Bot) GetMessage(ctx context.Context, chat ChatID, messageID int) (*Message, error) {
+	p, err := b.resolvePeer(ctx, chat)
+	if err != nil {
+		return nil, err
+	}
+
+	ids := []tg.InputMessageClass{&tg.InputMessageID{ID: messageID}}
+
+	var (
+		res    tg.MessagesMessagesClass
+		rpcErr error
+	)
+
+	if ch, ok := p.(peers.Channel); ok {
+		res, rpcErr = b.raw.ChannelsGetMessages(ctx, &tg.ChannelsGetMessagesRequest{
+			Channel: ch.InputChannel(),
+			ID:      ids,
+		})
+	} else {
+		res, rpcErr = b.raw.MessagesGetMessages(ctx, ids)
+	}
+
+	if rpcErr != nil {
+		return nil, asAPIError(rpcErr)
+	}
+
+	msgs, ok := res.AsModified()
+	if !ok {
+		return nil, &Error{Code: 400, Description: "Bad Request: message not found"}
+	}
+
+	for _, m := range msgs.GetMessages() {
+		msg, ok := m.(*tg.Message)
+		if !ok || msg.ID != messageID {
+			continue
+		}
+
+		return b.convertMessage(ctx, msg)
+	}
+
+	return nil, &Error{Code: 400, Description: "Bad Request: message not found"}
+}

get_message_test.go

@@ -0,0 +1,51 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestGetMessageExposesRaw(t *testing.T) {
+	inv := newMockInvoker()
+
+	raw := &tg.Message{ID: 7, Message: "hi", PeerID: &tg.PeerChannel{ChannelID: 50}}
+	inv.reply(tg.ChannelsGetMessagesRequestTypeID, &tg.MessagesChannelMessages{
+		Messages: []tg.MessageClass{raw},
+	})
+
+	b := newMockBot(inv)
+
+	m, err := b.GetMessage(context.Background(), tdlibChannel(50), 7)
+	if err != nil {
+		t.Fatalf("GetMessage: %v", err)
+	}
+
+	if m.MessageID != 7 || m.Text != "hi" {
+		t.Fatalf("message = %#v", m)
+	}
+
+	if m.Raw() == nil || m.Raw().ID != 7 || m.Raw().Message != "hi" {
+		t.Fatalf("Raw() = %#v, want the fetched tg.Message", m.Raw())
+	}
+
+	var req tg.ChannelsGetMessagesRequest
+
+	inv.decode(t, tg.ChannelsGetMessagesRequestTypeID, &req)
+
+	if len(req.ID) != 1 {
+		t.Fatalf("requested ids = %#v", req.ID)
+	}
+}
+
+func TestGetMessageNotFound(t *testing.T) {
+	inv := newMockInvoker()
+	inv.reply(tg.ChannelsGetMessagesRequestTypeID, &tg.MessagesChannelMessages{})
+
+	b := newMockBot(inv)
+
+	if _, err := b.GetMessage(context.Background(), tdlibChannel(50), 7); err == nil {
+		t.Fatal("expected error for missing message")
+	}
+}

types_message.go

@@ -1,5 +1,7 @@
 package botapi
 
+import "github.com/gotd/td/tg"
+
 // MessageEntity represents one special entity in a text message (e.g. a
 // hashtag, link, or formatted run).
 type MessageEntity struct {
@@ -121,4 +123,15 @@ type Message struct {
 	PinnedMessage  *Message `json:"pinned_message,omitempty"`
 
 	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
+
+	// raw holds the original MTProto message this Message was converted from, or
+	// nil for synthesized stubs (e.g. reply_to/pinned placeholders). It is not
+	// serialized; reach it through Raw.
+	raw *tg.Message
 }
+
+// Raw returns the original MTProto message this Message was converted from, for
+// anything the typed Bot API surface does not expose. It is nil for messages
+// that were not converted from a live update — synthesized reply_to and pinned
+// placeholders, or values produced by JSON decoding.
+func (m *Message) Raw() *tg.Message { return m.raw }