docs(reference): regenerate after perf series

Picks up new symbols from the perf commits: Context typed fields and Set method, header/buf pool vars in client and transport.

.benchstats/after_step1.txt

@@ -0,0 +1,17 @@
+After: static-header-slices + bool-fast-path
+goos: darwin
+goarch: arm64
+pkg: github.com/lukaszraczylo/go-telegram/client
+cpu: Apple M4 Max
+BenchmarkCall_BoolResponse-16      	 4597374	       526.3 ns/op	    1842 B/op	      14 allocs/op
+BenchmarkCall_StructResponse-16    	 3740096	       679.6 ns/op	    1973 B/op	      16 allocs/op
+BenchmarkEncodeJSONBody-16         	41997352	        58.35 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	863273641	         2.872 ns/op	       0 B/op	       0 allocs/op
+BenchmarkDecodeResult_Struct-16    	19988096	       100.3 ns/op	     144 B/op	       2 allocs/op
+
+Deltas vs baseline (allocs/op):
+  Call_BoolResponse:    18 -> 14 (-4)
+  Call_StructResponse:  18 -> 16 (-2)
+  DecodeResult_Bool:     2 -> 0  (-2, also -94% ns)
+  DecodeResult_Struct:   2 -> 2  (flat)
+  EncodeJSONBody:        2 -> 2  (flat)

.benchstats/after_step2.txt

@@ -0,0 +1,27 @@
+After: static-headers + bool-fast-path + lazy-Context.Values
+goos: darwin
+goarch: arm64
+cpu: Apple M4 Max
+
+pkg: github.com/lukaszraczylo/go-telegram/client
+BenchmarkCall_BoolResponse-16      	 4597374	       526.3 ns/op	    1842 B/op	      14 allocs/op
+BenchmarkCall_StructResponse-16    	 3740096	       679.6 ns/op	    1973 B/op	      16 allocs/op
+BenchmarkEncodeJSONBody-16         	41997352	        58.35 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	863273641	         2.872 ns/op	       0 B/op	       0 allocs/op
+BenchmarkDecodeResult_Struct-16    	19988096	       100.3 ns/op	     144 B/op	       2 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/dispatch
+BenchmarkRouter_DispatchCommand-16      	14912385	       156.4 ns/op	     416 B/op	       5 allocs/op
+BenchmarkRouter_DispatchTextRegex-16    	12495229	       187.7 ns/op	     428 B/op	       5 allocs/op
+BenchmarkRouter_DispatchFilter-16       	148631502	        16.11 ns/op	      48 B/op	       1 allocs/op
+BenchmarkRouter_NewContext-16           	1000000000	         1.608 ns/op	       0 B/op	       0 allocs/op
+BenchmarkExtractCommand-16              	25267845	        92.52 ns/op	       0 B/op	       0 allocs/op
+
+Cumulative deltas vs baseline:
+  Call_BoolResponse:    18 -> 14 allocs (-4)
+  Call_StructResponse:  18 -> 16 allocs (-2)
+  DecodeResult_Bool:     2 -> 0  allocs (-2, also 50ns -> 2.87ns)
+  DispatchFilter:        2 -> 1  alloc  (-1, also 32ns -> 16ns)
+  NewContext:            5.79ns -> 1.61ns (-72%)
+  DispatchCommand:       5 -> 5  allocs (flat — map alloc shifted from NewContext to first Set)
+  DispatchTextRegex:     5 -> 5  allocs (flat — same reason)

.benchstats/after_step3.txt

@@ -0,0 +1,27 @@
+After: static-headers + bool-fast-path + lazy-Values + typed-fields
+goos: darwin
+goarch: arm64
+cpu: Apple M4 Max
+
+pkg: github.com/lukaszraczylo/go-telegram/client
+BenchmarkCall_BoolResponse-16      	 4597374	       526.3 ns/op	    1842 B/op	      14 allocs/op
+BenchmarkCall_StructResponse-16    	 3740096	       679.6 ns/op	    1973 B/op	      16 allocs/op
+BenchmarkEncodeJSONBody-16         	41997352	        58.35 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	863273641	         2.872 ns/op	       0 B/op	       0 allocs/op
+BenchmarkDecodeResult_Struct-16    	19988096	       100.3 ns/op	     144 B/op	       2 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/dispatch
+BenchmarkRouter_DispatchCommand-16      	34631486	        69.19 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_DispatchTextRegex-16    	23260198	       106.6 ns/op	     112 B/op	       2 allocs/op
+BenchmarkRouter_DispatchFilter-16       	126697654	        19.03 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_NewContext-16           	1000000000	         1.600 ns/op	       0 B/op	       0 allocs/op
+BenchmarkExtractCommand-16              	27345622	        87.25 ns/op	       0 B/op	       0 allocs/op
+
+Cumulative deltas vs baseline (allocs/op):
+  Call_BoolResponse:    18 -> 14 allocs (-4)
+  Call_StructResponse:  18 -> 16 allocs (-2)
+  DecodeResult_Bool:     2 -> 0  allocs (-2, also 50ns -> 2.87ns)
+  DispatchCommand:       5 -> 1  alloc  (-4, also 153ns -> 69ns)
+  DispatchTextRegex:     5 -> 2  allocs (-3, also 181ns -> 107ns)
+  DispatchFilter:        2 -> 1  alloc  (-1, but +48B from larger Context struct)
+  NewContext:            5.79ns -> 1.60ns (-72%)

.benchstats/after_step4.txt

@@ -0,0 +1,26 @@
+After: static-headers + bool-fast-path + lazy-Values + typed-fields + resp-buffer-pool
+goos: darwin
+goarch: arm64
+cpu: Apple M4 Max
+
+pkg: github.com/lukaszraczylo/go-telegram/client
+BenchmarkCall_BoolResponse-16      	 4811347	       478.7 ns/op	    1331 B/op	      13 allocs/op
+BenchmarkCall_StructResponse-16    	 4038770	       591.6 ns/op	    1462 B/op	      15 allocs/op
+BenchmarkEncodeJSONBody-16         	47025052	        51.30 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	853161562	         2.824 ns/op	       0 B/op	       0 allocs/op
+BenchmarkDecodeResult_Struct-16    	26811634	        88.80 ns/op	     144 B/op	       2 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/dispatch
+BenchmarkRouter_DispatchCommand-16      	34631486	        69.19 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_DispatchTextRegex-16    	23260198	       106.6 ns/op	     112 B/op	       2 allocs/op
+BenchmarkRouter_DispatchFilter-16       	126697654	        19.03 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_NewContext-16           	1000000000	         1.600 ns/op	       0 B/op	       0 allocs/op
+BenchmarkExtractCommand-16              	27345622	        87.25 ns/op	       0 B/op	       0 allocs/op
+
+Cumulative deltas vs baseline:
+  Call_BoolResponse:    634ns / 18 allocs / 1957B  ->  479ns / 13 allocs / 1331B  (-24% / -5 / -626B)
+  Call_StructResponse:  665ns / 18 allocs / 2005B  ->  592ns / 15 allocs / 1462B  (-11% / -3 / -543B)
+  DecodeResult_Bool:     50ns /  2 allocs /   80B  -> 2.8ns /  0 allocs /    0B
+  DispatchCommand:      153ns /  5 allocs /  416B  ->   69ns /  1 alloc  /   96B  (-55% / -4 / -320B)
+  DispatchTextRegex:    181ns /  5 allocs /  428B  ->  107ns /  2 allocs /  112B  (-41% / -3 / -316B)
+  DispatchFilter:        32ns /  2 allocs /   96B  ->   19ns /  1 alloc  /   96B  (-41% / -1)

.benchstats/after_step5.txt

@@ -0,0 +1,30 @@
+After: static-headers + bool-fast-path + lazy-Values + typed-fields + resp-buffer-pool + webhook-pool
+goos: darwin
+goarch: arm64
+cpu: Apple M4 Max
+
+pkg: github.com/lukaszraczylo/go-telegram/client
+BenchmarkCall_BoolResponse-16      	 4811347	       478.7 ns/op	    1331 B/op	      13 allocs/op
+BenchmarkCall_StructResponse-16    	 4038770	       591.6 ns/op	    1462 B/op	      15 allocs/op
+BenchmarkEncodeJSONBody-16         	47025052	        51.30 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	853161562	         2.824 ns/op	       0 B/op	       0 allocs/op
+BenchmarkDecodeResult_Struct-16    	26811634	        88.80 ns/op	     144 B/op	       2 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/transport
+BenchmarkWebhook_ServeHTTP-16    	 1204390	      2020 ns/op	    7648 B/op	      23 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/dispatch
+BenchmarkRouter_DispatchCommand-16      	34631486	        69.19 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_DispatchTextRegex-16    	23260198	       106.6 ns/op	     112 B/op	       2 allocs/op
+BenchmarkRouter_DispatchFilter-16       	126697654	        19.03 ns/op	      96 B/op	       1 allocs/op
+BenchmarkRouter_NewContext-16           	1000000000	         1.600 ns/op	       0 B/op	       0 allocs/op
+BenchmarkExtractCommand-16              	27345622	        87.25 ns/op	       0 B/op	       0 allocs/op
+
+Cumulative deltas vs baseline:
+  Call_BoolResponse:    634ns / 18 allocs / 1957B   ->  479ns / 13 / 1331B   (-24% / -5  / -626B)
+  Call_StructResponse:  665ns / 18 allocs / 2005B   ->  592ns / 15 / 1462B   (-11% / -3  / -543B)
+  DecodeResult_Bool:     50ns /  2 allocs /   80B   -> 2.8ns /  0 /    0B
+  Webhook_ServeHTTP:   2564ns / 24 allocs / 12707B  -> 2020ns / 23 / 7648B   (-21% / -1  / -5059B)
+  DispatchCommand:      153ns /  5 allocs /  416B   ->   69ns /  1 /   96B   (-55% / -4  / -320B)
+  DispatchTextRegex:    181ns /  5 allocs /  428B   ->  107ns /  2 /  112B   (-41% / -3  / -316B)
+  DispatchFilter:        32ns /  2 allocs /   96B   ->   19ns /  1 /   96B   (-41% / -1)

.benchstats/baseline.txt

@@ -0,0 +1,19 @@
+goos: darwin
+goarch: arm64
+pkg: github.com/lukaszraczylo/go-telegram/client
+cpu: Apple M4 Max
+BenchmarkCall_BoolResponse-16      	 1875306	       633.9 ns/op	    1957 B/op	      18 allocs/op
+BenchmarkCall_StructResponse-16    	 1805024	       665.2 ns/op	    2005 B/op	      18 allocs/op
+BenchmarkEncodeJSONBody-16         	23345811	        51.55 ns/op	      96 B/op	       2 allocs/op
+BenchmarkDecodeResult_Bool-16      	23832240	        50.37 ns/op	      80 B/op	       2 allocs/op
+BenchmarkDecodeResult_Struct-16    	13511192	        92.64 ns/op	     144 B/op	       2 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/transport
+BenchmarkWebhook_ServeHTTP-16    	  465798	      2564 ns/op	   12707 B/op	      24 allocs/op
+
+pkg: github.com/lukaszraczylo/go-telegram/dispatch
+BenchmarkRouter_DispatchCommand-16      	 7303522	       152.7 ns/op	     416 B/op	       5 allocs/op
+BenchmarkRouter_DispatchTextRegex-16    	 6740305	       180.5 ns/op	     428 B/op	       5 allocs/op
+BenchmarkRouter_DispatchFilter-16       	39479149	        32.18 ns/op	      96 B/op	       2 allocs/op
+BenchmarkRouter_NewContext-16           	208260764	         5.790 ns/op	       0 B/op	       0 allocs/op
+BenchmarkExtractCommand-16              	12988816	        92.69 ns/op	       0 B/op	       0 allocs/op

api/discriminator_unified_enum_test.go

@@ -0,0 +1,239 @@
+package api
+
+import (
+	"reflect"
+	"testing"
+
+	json "github.com/goccy/go-json"
+	"github.com/stretchr/testify/require"
+)
+
+// TestUnifiedEnum_BotCommandScopeType_Constants confirms the prose-form
+// discriminator detection promoted BotCommandScope's per-variant Type
+// fields into one shared enum.
+func TestUnifiedEnum_BotCommandScopeType_Constants(t *testing.T) {
+	require.IsType(t, BotCommandScopeType(""), BotCommandScopeTypeDefault)
+
+	got := []BotCommandScopeType{
+		BotCommandScopeTypeDefault,
+		BotCommandScopeTypeAllPrivateChats,
+		BotCommandScopeTypeAllGroupChats,
+		BotCommandScopeTypeAllChatAdministrators,
+		BotCommandScopeTypeChat,
+		BotCommandScopeTypeChatAdministrators,
+		BotCommandScopeTypeChatMember,
+	}
+	want := []string{
+		"default", "all_private_chats", "all_group_chats",
+		"all_chat_administrators", "chat", "chat_administrators", "chat_member",
+	}
+	require.Len(t, got, len(want))
+	for i, v := range got {
+		require.Equal(t, want[i], string(v))
+	}
+}
+
+// TestUnifiedEnum_InlineQueryResultType_VariantFields walks the variants
+// and asserts each one's Type field is the unified enum.
+func TestUnifiedEnum_InlineQueryResultType_VariantFields(t *testing.T) {
+	require.IsType(t, InlineQueryResultType(""), InlineQueryResultTypeArticle)
+
+	wantType := reflect.TypeOf(InlineQueryResultType(""))
+	cases := []any{
+		&InlineQueryResultArticle{},
+		&InlineQueryResultPhoto{},
+		&InlineQueryResultGif{},
+		&InlineQueryResultMpeg4Gif{},
+		&InlineQueryResultVideo{},
+		&InlineQueryResultAudio{},
+		&InlineQueryResultVoice{},
+		&InlineQueryResultDocument{},
+		&InlineQueryResultLocation{},
+		&InlineQueryResultVenue{},
+		&InlineQueryResultContact{},
+		&InlineQueryResultGame{},
+	}
+	for _, c := range cases {
+		rt := reflect.TypeOf(c).Elem()
+		f, ok := rt.FieldByName("Type")
+		require.True(t, ok, "%s missing Type field", rt.Name())
+		require.Equal(t, wantType, f.Type, "%s.Type type mismatch", rt.Name())
+	}
+}
+
+// TestUnifiedEnum_PassportElementErrorSource_VariantFields asserts the
+// retype landed on every variant of the PassportElementError union.
+func TestUnifiedEnum_PassportElementErrorSource_VariantFields(t *testing.T) {
+	require.IsType(t, PassportElementErrorSource(""), PassportElementErrorSourceData)
+
+	wantType := reflect.TypeOf(PassportElementErrorSource(""))
+	cases := []any{
+		&PassportElementErrorDataField{},
+		&PassportElementErrorFrontSide{},
+		&PassportElementErrorReverseSide{},
+		&PassportElementErrorSelfie{},
+		&PassportElementErrorFile{},
+		&PassportElementErrorFiles{},
+		&PassportElementErrorTranslationFile{},
+		&PassportElementErrorTranslationFiles{},
+		&PassportElementErrorUnspecified{},
+	}
+	for _, c := range cases {
+		rt := reflect.TypeOf(c).Elem()
+		f, ok := rt.FieldByName("Source")
+		require.True(t, ok, "%s missing Source field", rt.Name())
+		require.Equal(t, wantType, f.Type, "%s.Source type mismatch", rt.Name())
+	}
+}
+
+// TestUnifiedEnum_InputMediaType_Constants covers a media-shaped union
+// where the discriminator value is the wire identifier "animation",
+// "photo", etc.
+func TestUnifiedEnum_InputMediaType_Constants(t *testing.T) {
+	require.IsType(t, InputMediaType(""), InputMediaTypePhoto)
+
+	wantType := reflect.TypeOf(InputMediaType(""))
+	for _, c := range []any{
+		&InputMediaAnimation{},
+		&InputMediaAudio{},
+		&InputMediaDocument{},
+		&InputMediaPhoto{},
+		&InputMediaVideo{},
+	} {
+		rt := reflect.TypeOf(c).Elem()
+		f, ok := rt.FieldByName("Type")
+		require.True(t, ok, "%s missing Type field", rt.Name())
+		require.Equal(t, wantType, f.Type, "%s.Type type mismatch", rt.Name())
+	}
+}
+
+// TestUnifiedEnum_MenuButtonType_Constants covers the third single-Type
+// union pulled in by the prose detector.
+func TestUnifiedEnum_MenuButtonType_Constants(t *testing.T) {
+	require.IsType(t, MenuButtonType(""), MenuButtonTypeCommands)
+
+	wantType := reflect.TypeOf(MenuButtonType(""))
+	for _, c := range []any{
+		&MenuButtonCommands{},
+		&MenuButtonWebApp{},
+		&MenuButtonDefault{},
+	} {
+		rt := reflect.TypeOf(c).Elem()
+		f, ok := rt.FieldByName("Type")
+		require.True(t, ok, "%s missing Type field", rt.Name())
+		require.Equal(t, wantType, f.Type, "%s.Type type mismatch", rt.Name())
+	}
+}
+
+// TestUnifiedEnum_InlineQueryResultArticle_RoundTrip confirms the
+// auto-injected discriminator survives a marshal-unmarshal cycle on the
+// concrete variant and lands as the typed enum constant. There's no
+// generated UnmarshalInlineQueryResult — the union has no entry in
+// knownDiscriminators — so the round-trip targets the variant directly.
+func TestUnifiedEnum_InlineQueryResultArticle_RoundTrip(t *testing.T) {
+	orig := &InlineQueryResultArticle{
+		ID:    "x1",
+		Title: "test",
+	}
+	raw, err := json.Marshal(orig)
+	require.NoError(t, err)
+
+	var probe struct {
+		Type string `json:"type"`
+	}
+	require.NoError(t, json.Unmarshal(raw, &probe))
+	require.Equal(t, "article", probe.Type)
+
+	// Strip InputMessageContent before re-decoding: it's a sealed
+	// interface and the variant has no UnmarshalJSON helper to dispatch
+	// it. The discriminator round-trip is the property under test, not
+	// nested-union deserialisation.
+	var round struct {
+		Type  InlineQueryResultType `json:"type"`
+		ID    string                `json:"id"`
+		Title string                `json:"title"`
+	}
+	require.NoError(t, json.Unmarshal(raw, &round))
+	require.Equal(t, InlineQueryResultTypeArticle, round.Type)
+	require.Equal(t, orig.ID, round.ID)
+	require.Equal(t, orig.Title, round.Title)
+}
+
+// TestUnifiedEnum_PassportElementErrorDataField_RoundTrip mirrors the
+// above for the Source-discriminated union.
+func TestUnifiedEnum_PassportElementErrorDataField_RoundTrip(t *testing.T) {
+	orig := &PassportElementErrorDataField{
+		Type:      "personal_details",
+		FieldName: "first_name",
+		DataHash:  "abc",
+		Message:   "boom",
+	}
+	raw, err := json.Marshal(orig)
+	require.NoError(t, err)
+
+	var probe struct {
+		Source string `json:"source"`
+	}
+	require.NoError(t, json.Unmarshal(raw, &probe))
+	require.Equal(t, "data", probe.Source)
+
+	var round PassportElementErrorDataField
+	require.NoError(t, json.Unmarshal(raw, &round))
+	require.Equal(t, PassportElementErrorSourceData, round.Source)
+	require.Equal(t, orig.FieldName, round.FieldName)
+}
+
+// TestUnifiedEnum_BotCommandScopeChat_RoundTrip covers a bot-command
+// scope variant with a non-trivial extra field (ChatID).
+func TestUnifiedEnum_BotCommandScopeChat_RoundTrip(t *testing.T) {
+	orig := &BotCommandScopeChat{ChatID: ChatIDFromInt(42)}
+	raw, err := json.Marshal(orig)
+	require.NoError(t, err)
+
+	var probe struct {
+		Type string `json:"type"`
+	}
+	require.NoError(t, json.Unmarshal(raw, &probe))
+	require.Equal(t, "chat", probe.Type)
+
+	var round BotCommandScopeChat
+	require.NoError(t, json.Unmarshal(raw, &round))
+	require.Equal(t, BotCommandScopeTypeChat, round.Type)
+}
+
+// TestUnifiedEnum_InputMessageContent_NoEnumEmitted confirms the IMC
+// union — which dispatches structurally on field presence rather than a
+// shared discriminator — does NOT get a unified enum, since none of its
+// variants declare a single-value discriminator field.
+func TestUnifiedEnum_InputMessageContent_NoEnumEmitted(t *testing.T) {
+	for _, name := range []string{
+		"InputTextMessageContent",
+		"InputLocationMessageContent",
+		"InputVenueMessageContent",
+		"InputContactMessageContent",
+		"InputInvoiceMessageContent",
+	} {
+		switch name {
+		case "InputTextMessageContent":
+			rt := reflect.TypeOf(&InputTextMessageContent{}).Elem()
+			_, ok := rt.FieldByName("Type")
+			require.False(t, ok, "%s unexpectedly grew a Type field", name)
+		case "InputLocationMessageContent":
+			rt := reflect.TypeOf(&InputLocationMessageContent{}).Elem()
+			_, ok := rt.FieldByName("Type")
+			require.False(t, ok, "%s unexpectedly grew a Type field", name)
+		case "InputVenueMessageContent":
+			rt := reflect.TypeOf(&InputVenueMessageContent{}).Elem()
+			_, ok := rt.FieldByName("Type")
+			require.False(t, ok, "%s unexpectedly grew a Type field", name)
+		case "InputContactMessageContent":
+			rt := reflect.TypeOf(&InputContactMessageContent{}).Elem()
+			_, ok := rt.FieldByName("Type")
+			require.False(t, ok, "%s unexpectedly grew a Type field", name)
+		case "InputInvoiceMessageContent":
+			rt := reflect.TypeOf(&InputInvoiceMessageContent{}).Elem()
+			_, ok := rt.FieldByName("Type")
+			require.False(t, ok, "%s unexpectedly grew a Type field", name)
+		}
+	}
+}

api/emoji_enums_test.go

@@ -0,0 +1,96 @@
+package api
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/goccy/go-json"
+	"github.com/stretchr/testify/require"
+)
+
+// TestDiceEmoji_Constants pins the canonical six dice-emoji values so a
+// regen, refactor, or accidental rename can't silently break the wire
+// contract.
+func TestDiceEmoji_Constants(t *testing.T) {
+	cases := []struct {
+		name string
+		got  DiceEmoji
+		want string
+	}{
+		{"Dice", DiceEmojiDice, "🎲"},
+		{"Dart", DiceEmojiDart, "🎯"},
+		{"Basketball", DiceEmojiBasketball, "🏀"},
+		{"Football", DiceEmojiFootball, "⚽"},
+		{"Bowling", DiceEmojiBowling, "🎳"},
+		{"SlotMachine", DiceEmojiSlotMachine, "🎰"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			require.Equal(t, c.want, string(c.got))
+		})
+	}
+}
+
+// TestSendDiceParams_EmojiFieldType asserts the codegen override wired
+// SendDiceParams.Emoji to the typed enum (not plain string). Reflection
+// catches a regression even if the file compiles via implicit string
+// conversion of an untyped literal.
+func TestSendDiceParams_EmojiFieldType(t *testing.T) {
+	rt := reflect.TypeOf(SendDiceParams{})
+	f, ok := rt.FieldByName("Emoji")
+	require.True(t, ok, "SendDiceParams.Emoji not present")
+	require.Equal(t, "DiceEmoji", f.Type.Name())
+}
+
+// TestSendDiceParams_MarshalJSON exercises the marshalled wire form to
+// prove the typed enum still serialises as a JSON string holding the
+// raw emoji bytes — i.e. the type override doesn't accidentally
+// double-encode.
+func TestSendDiceParams_MarshalJSON(t *testing.T) {
+	p := &SendDiceParams{
+		ChatID: ChatIDFromInt(1),
+		Emoji:  DiceEmojiBasketball,
+	}
+	data, err := json.Marshal(p)
+	require.NoError(t, err)
+	require.Contains(t, string(data), `"emoji":"🏀"`)
+}
+
+// TestReactionEmoji_Constants spot-checks a representative slice of the
+// 73-value enum. A full enumeration would be redundant — the test is
+// here to lock the wire form, not to retest the const-block.
+func TestReactionEmoji_Constants(t *testing.T) {
+	require.Equal(t, "👍", string(ReactionEmojiThumbsUp))
+	require.Equal(t, "👎", string(ReactionEmojiThumbsDown))
+	require.Equal(t, "❤", string(ReactionEmojiHeart))
+	require.Equal(t, "🔥", string(ReactionEmojiFire))
+	require.Equal(t, "💯", string(ReactionEmojiHundredPoints))
+	require.Equal(t, "🤡", string(ReactionEmojiClown))
+}
+
+// TestReactionTypeEmoji_FieldType asserts the codegen override wired
+// ReactionTypeEmoji.Emoji to the typed enum.
+func TestReactionTypeEmoji_FieldType(t *testing.T) {
+	rt := reflect.TypeOf(ReactionTypeEmoji{})
+	f, ok := rt.FieldByName("Emoji")
+	require.True(t, ok, "ReactionTypeEmoji.Emoji not present")
+	require.Equal(t, "ReactionEmoji", f.Type.Name())
+}
+
+// TestReactionTypeEmoji_RoundTrip proves a typed-enum value survives
+// JSON marshal → unmarshal cycle without losing fidelity. The
+// discriminator MarshalJSON on ReactionTypeEmoji forces type="emoji",
+// so we set it explicitly here for symmetry with the unmarshal path.
+func TestReactionTypeEmoji_RoundTrip(t *testing.T) {
+	in := &ReactionTypeEmoji{
+		Type:  ReactionTypeKindEmoji,
+		Emoji: ReactionEmojiThumbsUp,
+	}
+	data, err := json.Marshal(in)
+	require.NoError(t, err)
+	require.Contains(t, string(data), `"emoji":"👍"`)
+
+	var out ReactionTypeEmoji
+	require.NoError(t, json.Unmarshal(data, &out))
+	require.Equal(t, ReactionEmojiThumbsUp, out.Emoji)
+}

api/enums.gen.go

@@ -21,6 +21,18 @@ const (
 	BackgroundTypeKindChatTheme BackgroundTypeKind = "chat_theme"
 )
 
+type BotCommandScopeType string
+
+const (
+	BotCommandScopeTypeDefault               BotCommandScopeType = "default"
+	BotCommandScopeTypeAllPrivateChats       BotCommandScopeType = "all_private_chats"
+	BotCommandScopeTypeAllGroupChats         BotCommandScopeType = "all_group_chats"
+	BotCommandScopeTypeAllChatAdministrators BotCommandScopeType = "all_chat_administrators"
+	BotCommandScopeTypeChat                  BotCommandScopeType = "chat"
+	BotCommandScopeTypeChatAdministrators    BotCommandScopeType = "chat_administrators"
+	BotCommandScopeTypeChatMember            BotCommandScopeType = "chat_member"
+)
+
 type ChatBoostSourceKind string
 
 const (
@@ -92,6 +104,75 @@ const (
 	InlineQueryResultGifThumbnailMimeTypeVideoOfMp4  InlineQueryResultGifThumbnailMimeType = "video/mp4"
 )
 
+type InlineQueryResultType string
+
+const (
+	InlineQueryResultTypeAudio    InlineQueryResultType = "audio"
+	InlineQueryResultTypeDocument InlineQueryResultType = "document"
+	InlineQueryResultTypeGif      InlineQueryResultType = "gif"
+	InlineQueryResultTypeMpeg4Gif InlineQueryResultType = "mpeg4_gif"
+	InlineQueryResultTypePhoto    InlineQueryResultType = "photo"
+	InlineQueryResultTypeSticker  InlineQueryResultType = "sticker"
+	InlineQueryResultTypeVideo    InlineQueryResultType = "video"
+	InlineQueryResultTypeVoice    InlineQueryResultType = "voice"
+	InlineQueryResultTypeArticle  InlineQueryResultType = "article"
+	InlineQueryResultTypeContact  InlineQueryResultType = "contact"
+	InlineQueryResultTypeGame     InlineQueryResultType = "game"
+	InlineQueryResultTypeLocation InlineQueryResultType = "location"
+	InlineQueryResultTypeVenue    InlineQueryResultType = "venue"
+)
+
+type InputMediaType string
+
+const (
+	InputMediaTypeAnimation InputMediaType = "animation"
+	InputMediaTypeAudio     InputMediaType = "audio"
+	InputMediaTypeDocument  InputMediaType = "document"
+	InputMediaTypeLivePhoto InputMediaType = "live_photo"
+	InputMediaTypePhoto     InputMediaType = "photo"
+	InputMediaTypeVideo     InputMediaType = "video"
+)
+
+type InputPaidMediaType string
+
+const (
+	InputPaidMediaTypeLivePhoto InputPaidMediaType = "live_photo"
+	InputPaidMediaTypePhoto     InputPaidMediaType = "photo"
+	InputPaidMediaTypeVideo     InputPaidMediaType = "video"
+)
+
+type InputPollMediaType string
+
+const (
+	InputPollMediaTypeAnimation InputPollMediaType = "animation"
+	InputPollMediaTypeAudio     InputPollMediaType = "audio"
+	InputPollMediaTypeDocument  InputPollMediaType = "document"
+	InputPollMediaTypeLivePhoto InputPollMediaType = "live_photo"
+	InputPollMediaTypeLocation  InputPollMediaType = "location"
+	InputPollMediaTypePhoto     InputPollMediaType = "photo"
+	InputPollMediaTypeVenue     InputPollMediaType = "venue"
+	InputPollMediaTypeVideo     InputPollMediaType = "video"
+)
+
+type InputPollOptionMediaType string
+
+const (
+	InputPollOptionMediaTypeAnimation InputPollOptionMediaType = "animation"
+	InputPollOptionMediaTypeLivePhoto InputPollOptionMediaType = "live_photo"
+	InputPollOptionMediaTypeLocation  InputPollOptionMediaType = "location"
+	InputPollOptionMediaTypePhoto     InputPollOptionMediaType = "photo"
+	InputPollOptionMediaTypeSticker   InputPollOptionMediaType = "sticker"
+	InputPollOptionMediaTypeVenue     InputPollOptionMediaType = "venue"
+	InputPollOptionMediaTypeVideo     InputPollOptionMediaType = "video"
+)
+
+type InputProfilePhotoType string
+
+const (
+	InputProfilePhotoTypeStatic   InputProfilePhotoType = "static"
+	InputProfilePhotoTypeAnimated InputProfilePhotoType = "animated"
+)
+
 type InputStickerFormat string
 
 const (
@@ -100,6 +181,13 @@ const (
 	InputStickerFormatVideo    InputStickerFormat = "video"
 )
 
+type InputStoryContentType string
+
+const (
+	InputStoryContentTypePhoto InputStoryContentType = "photo"
+	InputStoryContentTypeVideo InputStoryContentType = "video"
+)
+
 type KeyboardButtonStyle string
 
 const (
@@ -117,6 +205,14 @@ const (
 	MaskPositionPointChin     MaskPositionPoint = "chin"
 )
 
+type MenuButtonType string
+
+const (
+	MenuButtonTypeCommands MenuButtonType = "commands"
+	MenuButtonTypeWebApp   MenuButtonType = "web_app"
+	MenuButtonTypeDefault  MenuButtonType = "default"
+)
+
 type MessageEntityType string
 
 const (
@@ -212,6 +308,20 @@ const (
 	PassportElementErrorSelfieTypeInternalPassport PassportElementErrorSelfieType = "internal_passport"
 )
 
+type PassportElementErrorSource string
+
+const (
+	PassportElementErrorSourceData             PassportElementErrorSource = "data"
+	PassportElementErrorSourceFrontSide        PassportElementErrorSource = "front_side"
+	PassportElementErrorSourceReverseSide      PassportElementErrorSource = "reverse_side"
+	PassportElementErrorSourceSelfie           PassportElementErrorSource = "selfie"
+	PassportElementErrorSourceFile             PassportElementErrorSource = "file"
+	PassportElementErrorSourceFiles            PassportElementErrorSource = "files"
+	PassportElementErrorSourceTranslationFile  PassportElementErrorSource = "translation_file"
+	PassportElementErrorSourceTranslationFiles PassportElementErrorSource = "translation_files"
+	PassportElementErrorSourceUnspecified      PassportElementErrorSource = "unspecified"
+)
+
 type PassportElementErrorTranslationFileType string
 
 const (

api/enums.go

@@ -32,3 +32,107 @@ const (
 	UpdateChatBoost               UpdateType = "chat_boost"
 	UpdateRemovedChatBoost        UpdateType = "removed_chat_boost"
 )
+
+// DiceEmoji is the set of emoji values accepted by sendDice. Telegram's
+// canonical list is "🎲", "🎯", "🏀", "⚽", "🎳", "🎰". The codegen
+// scraper drops these values during regex extraction (multi-byte
+// boundary issues with curly-quoted emoji), so this enum is hand-
+// curated and wired into SendDiceParams.Emoji via the per-field type
+// override in cmd/genapi/emitter.go.
+type DiceEmoji string
+
+const (
+	DiceEmojiDice        DiceEmoji = "🎲"
+	DiceEmojiDart        DiceEmoji = "🎯"
+	DiceEmojiBasketball  DiceEmoji = "🏀"
+	DiceEmojiFootball    DiceEmoji = "⚽"
+	DiceEmojiBowling     DiceEmoji = "🎳"
+	DiceEmojiSlotMachine DiceEmoji = "🎰"
+)
+
+// ReactionEmoji is the set of emoji Telegram allows in a
+// ReactionTypeEmoji.Emoji value. Hand-curated from
+// https://core.telegram.org/bots/api#reactiontypeemoji because the
+// scraper's curly-quote regex strips the emoji literals (byte-boundary
+// issue on multi-byte sequences). Names mirror the Unicode CLDR short
+// name where one exists; otherwise a stable common-English label.
+// Telegram occasionally extends this set — passers of unrecognised
+// strings still type-check (ReactionEmoji is a string alias) so this
+// list need not block runtime use of newer values.
+type ReactionEmoji string
+
+const (
+	ReactionEmojiHeart                     ReactionEmoji = "❤"
+	ReactionEmojiThumbsUp                  ReactionEmoji = "👍"
+	ReactionEmojiThumbsDown                ReactionEmoji = "👎"
+	ReactionEmojiFire                      ReactionEmoji = "🔥"
+	ReactionEmojiSmilingFaceWithHearts     ReactionEmoji = "🥰"
+	ReactionEmojiClappingHands             ReactionEmoji = "👏"
+	ReactionEmojiBeamingFace               ReactionEmoji = "😁"
+	ReactionEmojiThinkingFace              ReactionEmoji = "🤔"
+	ReactionEmojiExplodingHead             ReactionEmoji = "🤯"
+	ReactionEmojiScreamingFace             ReactionEmoji = "😱"
+	ReactionEmojiCursingFace               ReactionEmoji = "🤬"
+	ReactionEmojiCryingFace                ReactionEmoji = "😢"
+	ReactionEmojiPartyPopper               ReactionEmoji = "🎉"
+	ReactionEmojiStarStruck                ReactionEmoji = "🤩"
+	ReactionEmojiVomiting                  ReactionEmoji = "🤮"
+	ReactionEmojiPileOfPoo                 ReactionEmoji = "💩"
+	ReactionEmojiFoldedHands               ReactionEmoji = "🙏"
+	ReactionEmojiOKHand                    ReactionEmoji = "👌"
+	ReactionEmojiDove                      ReactionEmoji = "🕊"
+	ReactionEmojiClown                     ReactionEmoji = "🤡"
+	ReactionEmojiYawning                   ReactionEmoji = "🥱"
+	ReactionEmojiWoozyFace                 ReactionEmoji = "🥴"
+	ReactionEmojiHeartEyes                 ReactionEmoji = "😍"
+	ReactionEmojiWhale                     ReactionEmoji = "🐳"
+	ReactionEmojiHeartOnFire               ReactionEmoji = "❤‍🔥"
+	ReactionEmojiNewMoonFace               ReactionEmoji = "🌚"
+	ReactionEmojiHotDog                    ReactionEmoji = "🌭"
+	ReactionEmojiHundredPoints             ReactionEmoji = "💯"
+	ReactionEmojiRollingOnFloor            ReactionEmoji = "🤣"
+	ReactionEmojiLightning                 ReactionEmoji = "⚡"
+	ReactionEmojiBanana                    ReactionEmoji = "🍌"
+	ReactionEmojiTrophy                    ReactionEmoji = "🏆"
+	ReactionEmojiBrokenHeart               ReactionEmoji = "💔"
+	ReactionEmojiRaisedEyebrow             ReactionEmoji = "🤨"
+	ReactionEmojiNeutralFace               ReactionEmoji = "😐"
+	ReactionEmojiStrawberry                ReactionEmoji = "🍓"
+	ReactionEmojiChampagne                 ReactionEmoji = "🍾"
+	ReactionEmojiKissMark                  ReactionEmoji = "💋"
+	ReactionEmojiMiddleFinger              ReactionEmoji = "🖕"
+	ReactionEmojiDevil                     ReactionEmoji = "😈"
+	ReactionEmojiSleeping                  ReactionEmoji = "😴"
+	ReactionEmojiLoudlyCrying              ReactionEmoji = "😭"
+	ReactionEmojiNerd                      ReactionEmoji = "🤓"
+	ReactionEmojiGhost                     ReactionEmoji = "👻"
+	ReactionEmojiManTechnologist           ReactionEmoji = "👨‍💻"
+	ReactionEmojiEyes                      ReactionEmoji = "👀"
+	ReactionEmojiJackOLantern              ReactionEmoji = "🎃"
+	ReactionEmojiSeeNoEvil                 ReactionEmoji = "🙈"
+	ReactionEmojiHalo                      ReactionEmoji = "😇"
+	ReactionEmojiFearful                   ReactionEmoji = "😨"
+	ReactionEmojiHandshake                 ReactionEmoji = "🤝"
+	ReactionEmojiWriting                   ReactionEmoji = "✍"
+	ReactionEmojiHugging                   ReactionEmoji = "🤗"
+	ReactionEmojiSaluting                  ReactionEmoji = "🫡"
+	ReactionEmojiSantaClaus                ReactionEmoji = "🎅"
+	ReactionEmojiChristmasTree             ReactionEmoji = "🎄"
+	ReactionEmojiSnowman                   ReactionEmoji = "☃"
+	ReactionEmojiNailPolish                ReactionEmoji = "💅"
+	ReactionEmojiZanyFace                  ReactionEmoji = "🤪"
+	ReactionEmojiMoai                      ReactionEmoji = "🗿"
+	ReactionEmojiCool                      ReactionEmoji = "🆒"
+	ReactionEmojiHeartWithArrow            ReactionEmoji = "💘"
+	ReactionEmojiHearNoEvil                ReactionEmoji = "🙉"
+	ReactionEmojiUnicorn                   ReactionEmoji = "🦄"
+	ReactionEmojiKissingFace               ReactionEmoji = "😘"
+	ReactionEmojiPill                      ReactionEmoji = "💊"
+	ReactionEmojiSpeakNoEvil               ReactionEmoji = "🙊"
+	ReactionEmojiSmilingFaceWithSunglasses ReactionEmoji = "😎"
+	ReactionEmojiAlienMonster              ReactionEmoji = "👾"
+	ReactionEmojiManShrugging              ReactionEmoji = "🤷‍♂"
+	ReactionEmojiPersonShrugging           ReactionEmoji = "🤷"
+	ReactionEmojiWomanShrugging            ReactionEmoji = "🤷‍♀"
+	ReactionEmojiPoutingFace               ReactionEmoji = "😡"
+)

api/methods.gen.go

@@ -27,7 +27,7 @@ type GetUpdatesParams struct {
 	// Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling. Should be positive, short polling should be used for testing purposes only.
 	Timeout *int64 `json:"timeout,omitempty"`
 	// A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list of available update types. Specify an empty list to receive all update types except chat_member, message_reaction, and message_reaction_count (default). If not specified, the previous setting will be used.Please note that this parameter doesn't affect updates created before the call to getUpdates, so unwanted updates may be received for a short period of time.
-	AllowedUpdates []string `json:"allowed_updates,omitempty"`
+	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
 }
 
 // GetUpdates calls the getUpdates Telegram Bot API method.
@@ -54,7 +54,7 @@ type SetWebhookParams struct {
 	// The maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery, 1-100. Defaults to 40. Use lower values to limit the load on your bot's server, and higher values to increase your bot's throughput.
 	MaxConnections *int64 `json:"max_connections,omitempty"`
 	// A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. See Update for a complete list of available update types. Specify an empty list to receive all update types except chat_member, message_reaction, and message_reaction_count (default). If not specified, the previous setting will be used.Please note that this parameter doesn't affect updates created before the call to the setWebhook, so unwanted updates may be received for a short period of time.
-	AllowedUpdates []string `json:"allowed_updates,omitempty"`
+	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
 	// Pass True to drop all pending updates
 	DropPendingUpdates *bool `json:"drop_pending_updates,omitempty"`
 	// A secret token to be sent in a header “X-Telegram-Bot-Api-Secret-Token” in every webhook request, 1-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed. The header is useful to ensure that the request comes from a webhook set by you.
@@ -1953,7 +1953,7 @@ type SendDiceParams struct {
 	// Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat
 	DirectMessagesTopicID *int64 `json:"direct_messages_topic_id,omitempty"`
 	// Emoji on which the dice throw animation is based. Currently, must be one of “”, “”, “”, “”, “”, or “”. Dice can have values 1-6 for “”, “” and “”, values 1-5 for “” and “”, and values 1-64 for “”. Defaults to “”
-	Emoji string `json:"emoji,omitempty"`
+	Emoji DiceEmoji `json:"emoji,omitempty"`
 	// Sends the message silently. Users will receive a notification with no sound.
 	DisableNotification *bool `json:"disable_notification,omitempty"`
 	// Protects the contents of the sent message from forwarding

api/types.gen.go

@@ -91,7 +91,7 @@ type WebhookInfo struct {
 	// Optional. The maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery
 	MaxConnections *int64 `json:"max_connections,omitempty"`
 	// Optional. A list of update types the bot is subscribed to. Defaults to all update types except chat_member
-	AllowedUpdates []string `json:"allowed_updates,omitempty"`
+	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
 }
 
 // This object represents a Telegram user or bot.
@@ -3472,7 +3472,7 @@ type ReactionTypeEmoji struct {
 	// Type of the reaction, always “emoji”
 	Type ReactionTypeKind `json:"type"`
 	// Reaction emoji. Currently, it can be one of "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""
-	Emoji string `json:"emoji"`
+	Emoji ReactionEmoji `json:"emoji"`
 }
 
 // MarshalJSON encodes ReactionTypeEmoji with the discriminator field
@@ -4082,7 +4082,7 @@ func (*BotCommandScopeChatMember) isBotCommandScope() {}
 // Represents the default scope of bot commands. Default commands are used if no commands with a narrower scope are specified for the user.
 type BotCommandScopeDefault struct {
 	// Scope type, must be default
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 }
 
 // MarshalJSON encodes BotCommandScopeDefault with the discriminator field
@@ -4104,7 +4104,7 @@ func (v *BotCommandScopeDefault) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering all private chats.
 type BotCommandScopeAllPrivateChats struct {
 	// Scope type, must be all_private_chats
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 }
 
 // MarshalJSON encodes BotCommandScopeAllPrivateChats with the discriminator field
@@ -4126,7 +4126,7 @@ func (v *BotCommandScopeAllPrivateChats) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering all group and supergroup chats.
 type BotCommandScopeAllGroupChats struct {
 	// Scope type, must be all_group_chats
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 }
 
 // MarshalJSON encodes BotCommandScopeAllGroupChats with the discriminator field
@@ -4148,7 +4148,7 @@ func (v *BotCommandScopeAllGroupChats) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering all group and supergroup chat administrators.
 type BotCommandScopeAllChatAdministrators struct {
 	// Scope type, must be all_chat_administrators
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 }
 
 // MarshalJSON encodes BotCommandScopeAllChatAdministrators with the discriminator field
@@ -4170,7 +4170,7 @@ func (v *BotCommandScopeAllChatAdministrators) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering a specific chat.
 type BotCommandScopeChat struct {
 	// Scope type, must be chat
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 	// Unique identifier for the target chat or username of the target supergroup in the format @username. Channel direct messages chats and channel chats aren't supported.
 	ChatID ChatID `json:"chat_id"`
 }
@@ -4194,7 +4194,7 @@ func (v *BotCommandScopeChat) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering all administrators of a specific group or supergroup chat.
 type BotCommandScopeChatAdministrators struct {
 	// Scope type, must be chat_administrators
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 	// Unique identifier for the target chat or username of the target supergroup in the format @username. Channel direct messages chats and channel chats aren't supported.
 	ChatID ChatID `json:"chat_id"`
 }
@@ -4218,7 +4218,7 @@ func (v *BotCommandScopeChatAdministrators) MarshalJSON() ([]byte, error) {
 // Represents the scope of bot commands, covering a specific member of a group or supergroup chat.
 type BotCommandScopeChatMember struct {
 	// Scope type, must be chat_member
-	Type string `json:"type"`
+	Type BotCommandScopeType `json:"type"`
 	// Unique identifier for the target chat or username of the target supergroup in the format @username. Channel direct messages chats and channel chats aren't supported.
 	ChatID ChatID `json:"chat_id"`
 	// Unique identifier of the target user
@@ -4307,7 +4307,7 @@ func UnmarshalMenuButton(data []byte) (MenuButton, error) {
 // Represents a menu button, which opens the bot's list of commands.
 type MenuButtonCommands struct {
 	// Type of the button, must be commands
-	Type string `json:"type"`
+	Type MenuButtonType `json:"type"`
 }
 
 // MarshalJSON encodes MenuButtonCommands with the discriminator field
@@ -4329,7 +4329,7 @@ func (v *MenuButtonCommands) MarshalJSON() ([]byte, error) {
 // Represents a menu button, which launches a Web App.
 type MenuButtonWebApp struct {
 	// Type of the button, must be web_app
-	Type string `json:"type"`
+	Type MenuButtonType `json:"type"`
 	// Text on the button
 	Text string `json:"text"`
 	// Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method answerWebAppQuery. Alternatively, a t.me link to a Web App of the bot can be specified in the object instead of the Web App's URL, in which case the Web App will be opened as if the user pressed the link.
@@ -4355,7 +4355,7 @@ func (v *MenuButtonWebApp) MarshalJSON() ([]byte, error) {
 // Describes that no specific value for the menu button was set.
 type MenuButtonDefault struct {
 	// Type of the button, must be default
-	Type string `json:"type"`
+	Type MenuButtonType `json:"type"`
 }
 
 // MarshalJSON encodes MenuButtonDefault with the discriminator field
@@ -4711,7 +4711,7 @@ func (*InputMediaVideo) isInputMedia() {}
 // Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent.
 type InputMediaAnimation struct {
 	// Type of the result, must be animation
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
@@ -4753,7 +4753,7 @@ func (v *InputMediaAnimation) MarshalJSON() ([]byte, error) {
 // Represents an audio file to be treated as music to be sent.
 type InputMediaAudio struct {
 	// Type of the result, must be audio
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
@@ -4791,7 +4791,7 @@ func (v *InputMediaAudio) MarshalJSON() ([]byte, error) {
 // Represents a general file to be sent.
 type InputMediaDocument struct {
 	// Type of the result, must be document
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
@@ -4825,7 +4825,7 @@ func (v *InputMediaDocument) MarshalJSON() ([]byte, error) {
 // Represents a live photo to be sent.
 type InputMediaLivePhoto struct {
 	// Type of the result, must be live_photo
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// Video of the live photo to send. Pass a file_id to send a file that exists on the Telegram servers (recommended) or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files ». Sending live photos by a URL is currently unsupported.
 	Media string `json:"media"`
 	// The static photo to send. Pass a file_id to send a file that exists on the Telegram servers (recommended) or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files ». Sending live photos by a URL is currently unsupported.
@@ -4861,7 +4861,7 @@ func (v *InputMediaLivePhoto) MarshalJSON() ([]byte, error) {
 // Represents a location to be sent.
 type InputMediaLocation struct {
 	// Type of the result, must be location
-	Type string `json:"type"`
+	Type InputPollOptionMediaType `json:"type"`
 	// Latitude of the location
 	Latitude float64 `json:"latitude"`
 	// Longitude of the location
@@ -4889,7 +4889,7 @@ func (v *InputMediaLocation) MarshalJSON() ([]byte, error) {
 // Represents a photo to be sent.
 type InputMediaPhoto struct {
 	// Type of the result, must be photo
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Caption of the photo to be sent, 0-1024 characters after entities parsing
@@ -4923,7 +4923,7 @@ func (v *InputMediaPhoto) MarshalJSON() ([]byte, error) {
 // Represents a sticker file to be sent.
 type InputMediaSticker struct {
 	// Type of the result, must be sticker
-	Type string `json:"type"`
+	Type InputPollOptionMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a .WEBP sticker from the Internet, or pass “attach://<file_attach_name>” to upload a new .WEBP, .TGS, or .WEBM sticker using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Emoji associated with the sticker; only for just uploaded stickers
@@ -4949,7 +4949,7 @@ func (v *InputMediaSticker) MarshalJSON() ([]byte, error) {
 // Represents a venue to be sent.
 type InputMediaVenue struct {
 	// Type of the result, must be venue
-	Type string `json:"type"`
+	Type InputPollOptionMediaType `json:"type"`
 	// Latitude of the location
 	Latitude float64 `json:"latitude"`
 	// Longitude of the location
@@ -4987,7 +4987,7 @@ func (v *InputMediaVenue) MarshalJSON() ([]byte, error) {
 // Represents a video to be sent.
 type InputMediaVideo struct {
 	// Type of the result, must be video
-	Type string `json:"type"`
+	Type InputMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
@@ -5053,7 +5053,7 @@ func (*InputPaidMediaVideo) isInputPaidMedia() {}
 // The paid media to send is a live photo.
 type InputPaidMediaLivePhoto struct {
 	// Type of the media, must be live_photo
-	Type string `json:"type"`
+	Type InputPaidMediaType `json:"type"`
 	// Video of the live photo to send. Pass a file_id to send a file that exists on the Telegram servers (recommended) or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files ». Sending live photos by a URL is currently unsupported.
 	Media string `json:"media"`
 	// The static photo to send. Pass a file_id to send a file that exists on the Telegram servers (recommended) or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files ». Sending live photos by a URL is currently unsupported.
@@ -5079,7 +5079,7 @@ func (v *InputPaidMediaLivePhoto) MarshalJSON() ([]byte, error) {
 // The paid media to send is a photo.
 type InputPaidMediaPhoto struct {
 	// Type of the media, must be photo
-	Type string `json:"type"`
+	Type InputPaidMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 }
@@ -5103,7 +5103,7 @@ func (v *InputPaidMediaPhoto) MarshalJSON() ([]byte, error) {
 // The paid media to send is a video.
 type InputPaidMediaVideo struct {
 	// Type of the media, must be video
-	Type string `json:"type"`
+	Type InputPaidMediaType `json:"type"`
 	// File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files »
 	Media string `json:"media"`
 	// Optional. Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
@@ -5155,7 +5155,7 @@ func (*InputProfilePhotoAnimated) isInputProfilePhoto() {}
 // A static profile photo in the .JPG format.
 type InputProfilePhotoStatic struct {
 	// Type of the profile photo, must be static
-	Type string `json:"type"`
+	Type InputProfilePhotoType `json:"type"`
 	// The static profile photo. Profile photos can't be reused and can only be uploaded as a new file, so you can pass “attach://<file_attach_name>” if the photo was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
 	Photo string `json:"photo"`
 }
@@ -5179,7 +5179,7 @@ func (v *InputProfilePhotoStatic) MarshalJSON() ([]byte, error) {
 // An animated profile photo in the MPEG4 format.
 type InputProfilePhotoAnimated struct {
 	// Type of the profile photo, must be animated
-	Type string `json:"type"`
+	Type InputProfilePhotoType `json:"type"`
 	// The animated profile photo. Profile photos can't be reused and can only be uploaded as a new file, so you can pass “attach://<file_attach_name>” if the photo was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
 	Animation string `json:"animation"`
 	// Optional. Timestamp in seconds of the frame that will be used as the static profile photo. Defaults to 0.0.
@@ -5219,7 +5219,7 @@ func (*InputStoryContentVideo) isInputStoryContent() {}
 // Describes a photo to post as a story.
 type InputStoryContentPhoto struct {
 	// Type of the content, must be photo
-	Type string `json:"type"`
+	Type InputStoryContentType `json:"type"`
 	// The photo to post as a story. The photo must be of the size 1080x1920 and must not exceed 10 MB. The photo can't be reused and can only be uploaded as a new file, so you can pass “attach://<file_attach_name>” if the photo was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
 	Photo string `json:"photo"`
 }
@@ -5243,7 +5243,7 @@ func (v *InputStoryContentPhoto) MarshalJSON() ([]byte, error) {
 // Describes a video to post as a story.
 type InputStoryContentVideo struct {
 	// Type of the content, must be video
-	Type string `json:"type"`
+	Type InputStoryContentType `json:"type"`
 	// The video to post as a story. The video must be of the size 720x1280, streamable, encoded with H.265 codec, with key frames added each second in the MPEG4 format, and must not exceed 30 MB. The video can't be reused and can only be uploaded as a new file, so you can pass “attach://<file_attach_name>” if the video was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files »
 	Video string `json:"video"`
 	// Optional. Precise duration of the video in seconds; 0-60
@@ -5460,7 +5460,7 @@ func (*InlineQueryResultVoice) isInlineQueryResult() {}
 // Represents a link to an article or web page.
 type InlineQueryResultArticle struct {
 	// Type of the result, must be article
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 Bytes
 	ID string `json:"id"`
 	// Title of the result
@@ -5500,7 +5500,7 @@ func (v *InlineQueryResultArticle) MarshalJSON() ([]byte, error) {
 // Represents a link to a photo. By default, this photo will be sent by the user with optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the photo.
 type InlineQueryResultPhoto struct {
 	// Type of the result, must be photo
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL of the photo. Photo must be in JPEG format. Photo size must not exceed 5MB
@@ -5548,7 +5548,7 @@ func (v *InlineQueryResultPhoto) MarshalJSON() ([]byte, error) {
 // Represents a link to an animated GIF file. By default, this animated GIF file will be sent by the user with optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the animation.
 type InlineQueryResultGif struct {
 	// Type of the result, must be gif
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL for the GIF file
@@ -5598,7 +5598,7 @@ func (v *InlineQueryResultGif) MarshalJSON() ([]byte, error) {
 // Represents a link to a video animation (H.264/MPEG-4 AVC video without sound). By default, this animated MPEG-4 file will be sent by the user with optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the animation.
 type InlineQueryResultMpeg4Gif struct {
 	// Type of the result, must be mpeg4_gif
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL for the MPEG4 file
@@ -5649,7 +5649,7 @@ func (v *InlineQueryResultMpeg4Gif) MarshalJSON() ([]byte, error) {
 // If an InlineQueryResultVideo message contains an embedded video (e.g., YouTube), you must replace its content using input_message_content.
 type InlineQueryResultVideo struct {
 	// Type of the result, must be video
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL for the embedded video player or video file
@@ -5701,7 +5701,7 @@ func (v *InlineQueryResultVideo) MarshalJSON() ([]byte, error) {
 // Represents a link to an MP3 audio file. By default, this audio file will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the audio.
 type InlineQueryResultAudio struct {
 	// Type of the result, must be audio
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL for the audio file
@@ -5743,7 +5743,7 @@ func (v *InlineQueryResultAudio) MarshalJSON() ([]byte, error) {
 // Represents a link to a voice recording in an .OGG container encoded with OPUS. By default, this voice recording will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the the voice message.
 type InlineQueryResultVoice struct {
 	// Type of the result, must be voice
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid URL for the voice recording
@@ -5783,7 +5783,7 @@ func (v *InlineQueryResultVoice) MarshalJSON() ([]byte, error) {
 // Represents a link to a file. By default, this file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the file. Currently, only .PDF and .ZIP files can be sent using this method.
 type InlineQueryResultDocument struct {
 	// Type of the result, must be document
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// Title for the result
@@ -5831,7 +5831,7 @@ func (v *InlineQueryResultDocument) MarshalJSON() ([]byte, error) {
 // Represents a location on a map. By default, the location will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the location.
 type InlineQueryResultLocation struct {
 	// Type of the result, must be location
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 Bytes
 	ID string `json:"id"`
 	// Location latitude in degrees
@@ -5879,7 +5879,7 @@ func (v *InlineQueryResultLocation) MarshalJSON() ([]byte, error) {
 // Represents a venue. By default, the venue will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the venue.
 type InlineQueryResultVenue struct {
 	// Type of the result, must be venue
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 Bytes
 	ID string `json:"id"`
 	// Latitude of the venue location in degrees
@@ -5929,7 +5929,7 @@ func (v *InlineQueryResultVenue) MarshalJSON() ([]byte, error) {
 // Represents a contact with a phone number. By default, this contact will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the contact.
 type InlineQueryResultContact struct {
 	// Type of the result, must be contact
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 Bytes
 	ID string `json:"id"`
 	// Contact's phone number
@@ -5971,7 +5971,7 @@ func (v *InlineQueryResultContact) MarshalJSON() ([]byte, error) {
 // Represents a Game.
 type InlineQueryResultGame struct {
 	// Type of the result, must be game
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// Short name of the game
@@ -5999,7 +5999,7 @@ func (v *InlineQueryResultGame) MarshalJSON() ([]byte, error) {
 // Represents a link to a photo stored on the Telegram servers. By default, this photo will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the photo.
 type InlineQueryResultCachedPhoto struct {
 	// Type of the result, must be photo
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier of the photo
@@ -6041,7 +6041,7 @@ func (v *InlineQueryResultCachedPhoto) MarshalJSON() ([]byte, error) {
 // Represents a link to an animated GIF file stored on the Telegram servers. By default, this animated GIF file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with specified content instead of the animation.
 type InlineQueryResultCachedGif struct {
 	// Type of the result, must be gif
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier for the GIF file
@@ -6081,7 +6081,7 @@ func (v *InlineQueryResultCachedGif) MarshalJSON() ([]byte, error) {
 // Represents a link to a video animation (H.264/MPEG-4 AVC video without sound) stored on the Telegram servers. By default, this animated MPEG-4 file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the animation.
 type InlineQueryResultCachedMpeg4Gif struct {
 	// Type of the result, must be mpeg4_gif
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier for the MPEG4 file
@@ -6121,7 +6121,7 @@ func (v *InlineQueryResultCachedMpeg4Gif) MarshalJSON() ([]byte, error) {
 // Represents a link to a sticker stored on the Telegram servers. By default, this sticker will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the sticker.
 type InlineQueryResultCachedSticker struct {
 	// Type of the result, must be sticker
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier of the sticker
@@ -6151,7 +6151,7 @@ func (v *InlineQueryResultCachedSticker) MarshalJSON() ([]byte, error) {
 // Represents a link to a file stored on the Telegram servers. By default, this file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the file.
 type InlineQueryResultCachedDocument struct {
 	// Type of the result, must be document
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// Title for the result
@@ -6191,7 +6191,7 @@ func (v *InlineQueryResultCachedDocument) MarshalJSON() ([]byte, error) {
 // Represents a link to a video file stored on the Telegram servers. By default, this video file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the video.
 type InlineQueryResultCachedVideo struct {
 	// Type of the result, must be video
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier for the video file
@@ -6233,7 +6233,7 @@ func (v *InlineQueryResultCachedVideo) MarshalJSON() ([]byte, error) {
 // Represents a link to a voice message stored on the Telegram servers. By default, this voice message will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the voice message.
 type InlineQueryResultCachedVoice struct {
 	// Type of the result, must be voice
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier for the voice message
@@ -6271,7 +6271,7 @@ func (v *InlineQueryResultCachedVoice) MarshalJSON() ([]byte, error) {
 // Represents a link to an MP3 audio file stored on the Telegram servers. By default, this audio file will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified content instead of the audio.
 type InlineQueryResultCachedAudio struct {
 	// Type of the result, must be audio
-	Type string `json:"type"`
+	Type InlineQueryResultType `json:"type"`
 	// Unique identifier for this result, 1-64 bytes
 	ID string `json:"id"`
 	// A valid file identifier for the audio file
@@ -7172,7 +7172,7 @@ func (*PassportElementErrorUnspecified) isPassportElementError() {}
 // Represents an issue in one of the data fields that was provided by the user. The error is considered resolved when the field's value changes.
 type PassportElementErrorDataField struct {
 	// Error source, must be data
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the error, one of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address”
 	Type PassportElementErrorDataFieldType `json:"type"`
 	// Name of the data field which has the error
@@ -7202,7 +7202,7 @@ func (v *PassportElementErrorDataField) MarshalJSON() ([]byte, error) {
 // Represents an issue with the front side of a document. The error is considered resolved when the file with the front side of the document changes.
 type PassportElementErrorFrontSide struct {
 	// Error source, must be front_side
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the issue, one of “passport”, “driver_license”, “identity_card”, “internal_passport”
 	Type PassportElementErrorSelfieType `json:"type"`
 	// Base64-encoded hash of the file with the front side of the document
@@ -7230,7 +7230,7 @@ func (v *PassportElementErrorFrontSide) MarshalJSON() ([]byte, error) {
 // Represents an issue with the reverse side of a document. The error is considered resolved when the file with reverse side of the document changes.
 type PassportElementErrorReverseSide struct {
 	// Error source, must be reverse_side
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the issue, one of “driver_license”, “identity_card”
 	Type PassportElementErrorReverseSideType `json:"type"`
 	// Base64-encoded hash of the file with the reverse side of the document
@@ -7258,7 +7258,7 @@ func (v *PassportElementErrorReverseSide) MarshalJSON() ([]byte, error) {
 // Represents an issue with the selfie with a document. The error is considered resolved when the file with the selfie changes.
 type PassportElementErrorSelfie struct {
 	// Error source, must be selfie
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the issue, one of “passport”, “driver_license”, “identity_card”, “internal_passport”
 	Type PassportElementErrorSelfieType `json:"type"`
 	// Base64-encoded hash of the file with the selfie
@@ -7286,7 +7286,7 @@ func (v *PassportElementErrorSelfie) MarshalJSON() ([]byte, error) {
 // Represents an issue with a document scan. The error is considered resolved when the file with the document scan changes.
 type PassportElementErrorFile struct {
 	// Error source, must be file
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the issue, one of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
 	Type PassportElementErrorFileType `json:"type"`
 	// Base64-encoded file hash
@@ -7314,7 +7314,7 @@ func (v *PassportElementErrorFile) MarshalJSON() ([]byte, error) {
 // Represents an issue with a list of scans. The error is considered resolved when the list of files containing the scans changes.
 type PassportElementErrorFiles struct {
 	// Error source, must be files
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// The section of the user's Telegram Passport which has the issue, one of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
 	Type PassportElementErrorFileType `json:"type"`
 	// List of base64-encoded file hashes
@@ -7342,7 +7342,7 @@ func (v *PassportElementErrorFiles) MarshalJSON() ([]byte, error) {
 // Represents an issue with one of the files that constitute the translation of a document. The error is considered resolved when the file changes.
 type PassportElementErrorTranslationFile struct {
 	// Error source, must be translation_file
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// Type of element of the user's Telegram Passport which has the issue, one of “passport”, “driver_license”, “identity_card”, “internal_passport”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
 	Type PassportElementErrorTranslationFileType `json:"type"`
 	// Base64-encoded file hash
@@ -7370,7 +7370,7 @@ func (v *PassportElementErrorTranslationFile) MarshalJSON() ([]byte, error) {
 // Represents an issue with the translated version of a document. The error is considered resolved when a file with the document translation change.
 type PassportElementErrorTranslationFiles struct {
 	// Error source, must be translation_files
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// Type of element of the user's Telegram Passport which has the issue, one of “passport”, “driver_license”, “identity_card”, “internal_passport”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
 	Type PassportElementErrorTranslationFileType `json:"type"`
 	// List of base64-encoded file hashes
@@ -7398,7 +7398,7 @@ func (v *PassportElementErrorTranslationFiles) MarshalJSON() ([]byte, error) {
 // Represents an issue in an unspecified place. The error is considered resolved when new data is added.
 type PassportElementErrorUnspecified struct {
 	// Error source, must be unspecified
-	Source string `json:"source"`
+	Source PassportElementErrorSource `json:"source"`
 	// Type of element of the user's Telegram Passport which has the issue
 	Type string `json:"type"`
 	// Base64-encoded element hash

client/call.go

@@ -8,8 +8,36 @@ import (
 	"io"
 	"net/http"
 	"reflect"
+	"sync"
 )
 
+var (
+	headerJSONValue = []string{"application/json"}
+	rawOKTrueBody   = []byte(`{"ok":true,"result":true}`)
+	rawOKFalseBody  = []byte(`{"ok":true,"result":false}`)
+
+	// respBufPool reuses *bytes.Buffer for response body reads. Used on
+	// paths whose decoder copies strings out of the input (decodeResult,
+	// which delegates to goccy/go-json), so the buffer can be returned to
+	// the pool as soon as Unmarshal has run. CallRaw and callMultipartRaw
+	// return slices that alias the buffer and therefore cannot use the
+	// pool without an extra copy that would defeat the point.
+	respBufPool = sync.Pool{New: func() any { return new(bytes.Buffer) }}
+)
+
+// maxPooledBufCap caps the buffer size returned to respBufPool. Buffers
+// larger than this are dropped on the floor so a single huge response
+// (e.g. a large getFile metadata payload) doesn't bloat the pool for the
+// rest of the process lifetime.
+const maxPooledBufCap = 64 * 1024
+
+func putRespBuf(buf *bytes.Buffer) {
+	if buf.Cap() > maxPooledBufCap {
+		return
+	}
+	respBufPool.Put(buf)
+}
+
 // Call is the single point through which every Telegram Bot API method
 // invocation flows. It marshals the request, signs the URL with the bot
 // token, dispatches via HTTPDoer, decodes the Result envelope, and
@@ -44,8 +72,8 @@ func Call[Req any, Resp any](ctx context.Context, b *Bot, method string, req Req
 	if err != nil {
 		return zero, &NetworkError{Err: err}
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	httpReq.Header.Set("Accept", "application/json")
+	httpReq.Header["Content-Type"] = headerJSONValue
+	httpReq.Header["Accept"] = headerJSONValue
 
 	resp, err := b.http.Do(httpReq)
 	if err != nil {
@@ -57,12 +85,14 @@ func Call[Req any, Resp any](ctx context.Context, b *Bot, method string, req Req
 	}
 	defer func() { _ = resp.Body.Close() }()
 
-	raw, err := io.ReadAll(resp.Body)
-	if err != nil {
+	buf := respBufPool.Get().(*bytes.Buffer)
+	buf.Reset()
+	defer putRespBuf(buf)
+	if _, err := buf.ReadFrom(resp.Body); err != nil {
 		return zero, &NetworkError{Err: err}
 	}
 
-	return decodeResult[Resp](b.codec, raw)
+	return decodeResult[Resp](b.codec, buf.Bytes())
 }
 
 // CallRaw is like Call but returns the raw JSON of the result field
@@ -91,8 +121,8 @@ func CallRaw[Req any](ctx context.Context, b *Bot, method string, req Req) (json
 	if err != nil {
 		return nil, &NetworkError{Err: err}
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	httpReq.Header.Set("Accept", "application/json")
+	httpReq.Header["Content-Type"] = headerJSONValue
+	httpReq.Header["Accept"] = headerJSONValue
 
 	resp, err := b.http.Do(httpReq)
 	if err != nil {
@@ -139,8 +169,22 @@ func encodeJSONBody(codec Codec, req any) (io.Reader, error) {
 
 // decodeResult unmarshals raw into Result[Resp] and translates non-OK
 // responses into *APIError.
+//
+// Bool fast path: ~60% of Telegram methods return bool. The Telegram API
+// emits the result envelope with no whitespace, so a byte-equality check
+// against the two canonical bodies skips the generic Unmarshal entirely.
+// Anything that doesn't match exactly (e.g. responses with extra fields,
+// errors) falls through to the slow path.
 func decodeResult[Resp any](codec Codec, raw []byte) (Resp, error) {
 	var zero Resp
+	if _, isBool := any(zero).(bool); isBool {
+		switch {
+		case bytes.Equal(raw, rawOKTrueBody):
+			return any(true).(Resp), nil
+		case bytes.Equal(raw, rawOKFalseBody):
+			return any(false).(Resp), nil
+		}
+	}
 	var env Result[Resp]
 	if err := codec.Unmarshal(raw, &env); err != nil {
 		return zero, &ParseError{Err: err, Body: copyBody(raw)}

client/call_bench_test.go

@@ -0,0 +1,94 @@
+package client
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"testing"
+)
+
+// stubDoer returns the same canned response body for every request. It
+// is intentionally minimal — testify mock has its own overhead that
+// would dominate the per-call cost we want to measure.
+type stubDoer struct{ body []byte }
+
+func (s *stubDoer) Do(_ *http.Request) (*http.Response, error) {
+	return &http.Response{
+		StatusCode: http.StatusOK,
+		Body:       io.NopCloser(bytes.NewReader(s.body)),
+		Header:     http.Header{},
+	}, nil
+}
+
+type benchSendReq struct {
+	ChatID int64  `json:"chat_id"`
+	Text   string `json:"text"`
+}
+
+type benchMsgResp struct {
+	MessageID int64  `json:"message_id"`
+	Date      int64  `json:"date"`
+	Text      string `json:"text"`
+}
+
+func BenchmarkCall_BoolResponse(b *testing.B) {
+	d := &stubDoer{body: []byte(`{"ok":true,"result":true}`)}
+	bot := New("123:abc", WithHTTPClient(d))
+	ctx := context.Background()
+	req := &benchSendReq{ChatID: 42, Text: "hi"}
+	b.ReportAllocs()
+	for b.Loop() {
+		if _, err := Call[*benchSendReq, bool](ctx, bot, "setMyCommands", req); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkCall_StructResponse(b *testing.B) {
+	d := &stubDoer{body: []byte(`{"ok":true,"result":{"message_id":1,"date":0,"text":"ok"}}`)}
+	bot := New("123:abc", WithHTTPClient(d))
+	ctx := context.Background()
+	req := &benchSendReq{ChatID: 42, Text: "hi"}
+	b.ReportAllocs()
+	for b.Loop() {
+		if _, err := Call[*benchSendReq, benchMsgResp](ctx, bot, "sendMessage", req); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkEncodeJSONBody(b *testing.B) {
+	codec := DefaultCodec{}
+	req := &benchSendReq{ChatID: 42, Text: "hello, world"}
+	b.ReportAllocs()
+	for b.Loop() {
+		r, err := encodeJSONBody(codec, req)
+		if err != nil {
+			b.Fatal(err)
+		}
+		_ = r
+	}
+}
+
+func BenchmarkDecodeResult_Bool(b *testing.B) {
+	codec := DefaultCodec{}
+	raw := []byte(`{"ok":true,"result":true}`)
+	b.ReportAllocs()
+	for b.Loop() {
+		if _, err := decodeResult[bool](codec, raw); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkDecodeResult_Struct(b *testing.B) {
+	codec := DefaultCodec{}
+	raw := []byte(`{"ok":true,"result":{"message_id":1,"date":0,"text":"ok"}}`)
+	b.ReportAllocs()
+	for b.Loop() {
+		if _, err := decodeResult[benchMsgResp](codec, raw); err != nil {
+			b.Fatal(err)
+		}
+	}
+}

client/multipart.go

@@ -1,6 +1,7 @@
 package client
 
 import (
+	"bytes"
 	"context"
 	"github.com/goccy/go-json"
 	"io"
@@ -69,7 +70,7 @@ func callMultipart[Resp any](ctx context.Context, b *Bot, method string, mp mult
 		return zero, &NetworkError{Err: err}
 	}
 	req.Header.Set("Content-Type", mw.FormDataContentType())
-	req.Header.Set("Accept", "application/json")
+	req.Header["Accept"] = headerJSONValue
 
 	resp, err := b.http.Do(req)
 	if err != nil {
@@ -81,12 +82,14 @@ func callMultipart[Resp any](ctx context.Context, b *Bot, method string, mp mult
 	}
 	defer func() { _ = resp.Body.Close() }()
 
-	raw, err := io.ReadAll(resp.Body)
-	if err != nil {
+	buf := respBufPool.Get().(*bytes.Buffer)
+	buf.Reset()
+	defer putRespBuf(buf)
+	if _, err := buf.ReadFrom(resp.Body); err != nil {
 		_ = pr.CloseWithError(err)
 		return zero, &NetworkError{Err: err}
 	}
-	return decodeResult[Resp](b.codec, raw)
+	return decodeResult[Resp](b.codec, buf.Bytes())
 }
 
 // callMultipartRaw is callMultipart's sibling that returns the raw result
@@ -125,7 +128,7 @@ func callMultipartRaw(ctx context.Context, b *Bot, method string, mp multipartRe
 		return nil, &NetworkError{Err: err}
 	}
 	req.Header.Set("Content-Type", mw.FormDataContentType())
-	req.Header.Set("Accept", "application/json")
+	req.Header["Accept"] = headerJSONValue
 
 	resp, err := b.http.Do(req)
 	if err != nil {

cmd/genapi/emitter.go

@@ -46,6 +46,30 @@ var runtimeTypes = map[string]bool{
 	"MessageOrBool":      true,
 }
 
+// fieldTypeOverrides maps "<TypeOrParamsName>.<FieldName>" → Go type expression.
+// Used for fields whose values are restricted but whose enum the scraper
+// can't detect (Telegram's curly-quoted emoji literals are routinely
+// stripped by the scraper's regex due to byte-boundary issues with
+// multi-byte sequences). The hand-curated typed-string enum lives in
+// api/enums.go (manual file); this override just retypes the field so
+// callers get IDE completion and compile-time checks. Generated fields
+// stay typed even after `make regen`.
+var fieldTypeOverrides = map[string]string{
+	"ReactionTypeEmoji.Emoji": "ReactionEmoji",
+	"SendDiceParams.Emoji":    "DiceEmoji",
+}
+
+// fieldTypeOverride returns the override type for a (parent, fieldName)
+// pair, or "" if none. parent is the Go type name owning the field —
+// either a struct type (e.g. "ReactionTypeEmoji") or a method-params
+// type (e.g. "SendDiceParams").
+func fieldTypeOverride(parent, fieldName string) string {
+	if parent == "" {
+		return ""
+	}
+	return fieldTypeOverrides[parent+"."+fieldName]
+}
+
 // discriminatorSpec describes how to decode a sealed-interface union by
 // peeking at a single JSON field.
 type discriminatorSpec struct {
@@ -395,6 +419,9 @@ func funcs(plan *enumPlan) template.FuncMap {
 		"goField": func(parent string, f spec.Field) string {
 			return goField(plan, parent, f)
 		},
+		"goFieldP": func(methodName string, f spec.Field) string {
+			return goFieldX(plan, "", title(methodName)+"Params", f)
+		},
 		"docComment":  docComment,
 		"isOptional":  func(f spec.Field) bool { return !f.Required },
 		"not":         func(b bool) bool { return !b },
@@ -404,6 +431,9 @@ func funcs(plan *enumPlan) template.FuncMap {
 		"multipartFieldEntry": func(parent string, f spec.Field) string {
 			return multipartFieldEntry(plan, parent, f)
 		},
+		"multipartFieldEntryP": func(methodName string, f spec.Field) string {
+			return multipartFieldEntryX(plan, "", title(methodName)+"Params", f)
+		},
 		"multipartFileEntry": multipartFileEntry,
 		"returnGoType":       returnGoType,
 		// enum helpers
@@ -503,7 +533,17 @@ func multipartFileEntry(f spec.Field) string {
 // when non-zero/non-empty. Typed-string enum fields are cast to string
 // before assignment because the multipart map is map[string]string.
 func multipartFieldEntry(plan *enumPlan, parent string, f spec.Field) string {
-	enumName := plan.FieldEnum(parent, f.Name)
+	return multipartFieldEntryX(plan, parent, parent, f)
+}
+
+// multipartFieldEntryX mirrors goFieldX: enumParent keys the enum plan,
+// overrideParent keys fieldTypeOverrides. They differ only for method
+// params.
+func multipartFieldEntryX(plan *enumPlan, enumParent, overrideParent string, f spec.Field) string {
+	enumName := plan.FieldEnum(enumParent, f.Name)
+	if enumName == "" {
+		enumName = fieldTypeOverride(overrideParent, f.Name)
+	}
 	switch f.Type.Kind {
 	case spec.KindPrimitive:
 		switch f.Type.Name {
@@ -775,12 +815,40 @@ func matchesVariants(got []string, want ...string) bool {
 // has a planned enum name for (parent, field), the field's Go type is
 // the enum identifier. Typed-string enums use the zero string ""
 // behaviour for omitempty, so we do not pointer-wrap optional enum
-// fields. Parent is "" for method parameters.
+// fields. Parent is "" for method parameters; pass the params type
+// name (e.g. "SendDiceParams") via overrideParent when calling from
+// the methods template so fieldTypeOverrides can resolve.
 func goField(plan *enumPlan, parent string, f spec.Field) string {
+	return goFieldX(plan, parent, parent, f)
+}
+
+// goFieldX is the underlying field-emitter. enumParent is used for the
+// enum-plan lookup (which keys method params under ""); overrideParent
+// is used for fieldTypeOverrides (which keys method params under the
+// params type name). For struct types both are the same; for method
+// params they differ.
+func goFieldX(plan *enumPlan, enumParent, overrideParent string, f spec.Field) string {
 	tag := fmt.Sprintf("`json:%q`", f.JSONName+omitempty(f))
-	if name := plan.FieldEnum(parent, f.Name); name != "" {
+	if name := plan.FieldEnum(enumParent, f.Name); name != "" {
 		return fmt.Sprintf("%s %s %s", f.Name, name, tag)
 	}
+	if name := fieldTypeOverride(overrideParent, f.Name); name != "" {
+		return fmt.Sprintf("%s %s %s", f.Name, name, tag)
+	}
+	// Pinned companion-enum retype: allowed_updates is an Array of String
+	// in the upstream spec, but the Go API exposes a hand-curated
+	// UpdateType (api/enums.go) since the values are not enumerated
+	// inline by Telegram. Retype []string → []UpdateType wherever the
+	// wire field is allowed_updates so callers can pass typed constants
+	// (api.UpdateMessage, ...) without string casts. Wire format is
+	// unchanged: UpdateType is a typed string, marshals identically.
+	if f.JSONName == "allowed_updates" &&
+		f.Type.Kind == spec.KindArray &&
+		f.Type.ElemType != nil &&
+		f.Type.ElemType.Kind == spec.KindPrimitive &&
+		f.Type.ElemType.Name == "string" {
+		return fmt.Sprintf("%s []UpdateType %s", f.Name, tag)
+	}
 	return fmt.Sprintf("%s %s %s", f.Name, goType(f.Type, !f.Required), tag)
 }
 

cmd/genapi/methods.tmpl

@@ -15,12 +15,12 @@ import (
 var _ = strconv.Itoa  // keep import for multipart helpers
 var _ = json.Marshal  // keep import for complex multipart fields
 
-{{range .Methods}}
+{{range .Methods}}{{$methodName := .Name}}
 // {{title .Name}}Params is the parameter set for {{title .Name}}.
 //
 {{docComment .Doc -}}
 type {{title .Name}}Params struct {
-{{range .Params}}{{docComment .Doc}}	{{goField "" .}}
+{{range .Params}}{{docComment .Doc}}	{{goFieldP $methodName .}}
 {{end}}}
 {{if .HasFiles}}
 // HasFile reports whether a multipart upload is required.
@@ -31,7 +31,7 @@ func (p *{{title .Name}}Params) HasFile() bool {
 // MultipartFields returns the non-file fields used in the multipart body.
 func (p *{{title .Name}}Params) MultipartFields() map[string]string {
 	out := map[string]string{}
-{{range .Params}}{{if not (isFileField .)}}{{multipartFieldEntry "" .}}{{end}}{{end}}	return out
+{{range .Params}}{{if not (isFileField .)}}{{multipartFieldEntryP $methodName .}}{{end}}{{end}}	return out
 }
 
 // MultipartFiles returns the file parts.

cmd/scrape/enums.go

@@ -27,6 +27,33 @@ import (
 //     emits the canonical Markdown / MarkdownV2 / HTML triple.
 //
 // Returns nil when the description does not look like an enum.
+// extractEnumValues inspects a field-description string and returns the
+// list of wire-level string values when the description matches one of
+// the enum-like patterns Telegram uses in its docs. Order follows doc
+// order; duplicates are removed but order of first occurrence is kept.
+//
+// Handled patterns (curly quotes “…” are required to avoid false
+// positives on free-text quoting):
+//
+//   - "Type of the chat, can be either “private”, “group”, … or “channel”"
+//   - "Currently, can be “mention”, “hashtag”, …"
+//   - "Currently, one of “XTR” … or “TON” …"
+//   - "Currently, must be one of “XTR” …"
+//   - "Currently, it can be one of “pending”, “approved”, “declined”."
+//   - "Must be one of “danger” …, “success” …"
+//   - "Must be one of “image/jpeg”, “image/gif”, or “video/mp4”"
+//   - "Format … must be one of “static” …, “animated” …, “video” …"
+//   - "Currently, either “upgrade” …, “transfer” …, “resale” …"
+//   - "..., always “creator”"
+//   - parse_mode parameter special case ("Mode for parsing entities …")
+//     emits the canonical Markdown / MarkdownV2 / HTML triple.
+//   - bare prose discriminator at end of description, e.g.
+//     "Type of the result, must be article" or
+//     "Scope type, must be all_private_chats". Used by sealed-interface
+//     union variants whose Type/Source field carries a single literal
+//     value declared without curly quotes.
+//
+// Returns nil when the description does not look like an enum.
 func extractEnumValues(jsonName, desc string) []string {
 	if values := parseModeEnumValues(jsonName, desc); values != nil {
 		return values
@@ -34,12 +61,15 @@ func extractEnumValues(jsonName, desc string) []string {
 
 	trigger, triggerEnd, isAlways := findEnumTrigger(desc)
 	if trigger < 0 {
-		return nil
+		return extractProseDiscriminator(desc)
 	}
 	tail := desc[trigger:]
 
 	values := collectQuotedValues(tail)
 	if len(values) == 0 {
+		if v := extractProseDiscriminator(desc); v != nil {
+			return v
+		}
 		return nil
 	}
 	// First quoted value must sit close to the trigger phrase (e.g.
@@ -203,3 +233,59 @@ func dedupeStrings(in []string) []string {
 	}
 	return out
 }
+
+// proseDiscRE matches a terminal "must be <ident>" clause: the
+// discriminator value sits at the END of the description (optionally
+// followed by trailing punctuation/whitespace) so multi-clause prose
+// like "must be shown above the message" is not picked up.
+//
+// The identifier is a snake_case wire literal: lowercase letters, digits,
+// and underscores, starting with a letter. Numeric-only and prose words
+// are filtered separately by isProseWord.
+var proseDiscRE = regexp.MustCompile(`(?i)\bmust be\s+([a-z][a-z0-9_]*)\s*[.,]?\s*$`)
+
+// extractProseDiscriminator detects unambiguous single-value
+// discriminator declarations of the form "..., must be <ident>" used by
+// sealed-interface union variants (e.g. "Type of the result, must be
+// article" or "Scope type, must be all_private_chats"). Returns the
+// extracted value as a one-element slice or nil when no match is found.
+//
+// The terminal-position anchor is what protects against prose like
+// "must be shown above" or "must be one of 3, 6, or 12" — the candidate
+// must close the description.
+func extractProseDiscriminator(desc string) []string {
+	desc = strings.TrimSpace(desc)
+	if desc == "" {
+		return nil
+	}
+	m := proseDiscRE.FindStringSubmatch(desc)
+	if m == nil {
+		return nil
+	}
+	v := m[1]
+	if isProseWord(v) {
+		return nil
+	}
+	return []string{v}
+}
+
+// isProseWord rejects bare-prose continuations that pass the regex but
+// are clearly English filler ("must be sent", "must be available"). The
+// list is the closed set of words that empirically appear in the IR's
+// "must be …" tails outside the variant-discriminator pattern. Wire
+// identifiers are always single tokens with no English meaning, so any
+// match here is a free-text false positive.
+func isProseWord(s string) bool {
+	switch s {
+	case "a", "an", "the",
+		"sent", "shown", "set", "used", "passed", "specified", "available",
+		"applied", "supported", "assumed", "active", "paid", "between",
+		"of", "on", "in", "at", "by", "to", "from", "for", "with",
+		"and", "or", "no", "non",
+		"positive", "negative",
+		"administrator", "repainted",
+		"one", "exactly":
+		return true
+	}
+	return false
+}

cmd/scrape/enums_test.go

@@ -83,3 +83,56 @@ func TestExtractEnumValues_DedupeRepeatedValues(t *testing.T) {
 	got := extractEnumValues("currency", desc)
 	require.Equal(t, []string{"XTR"}, got)
 }
+
+func TestExtractEnumValues_ProseDiscriminator(t *testing.T) {
+	cases := []struct {
+		name string
+		desc string
+		want []string
+	}{
+		{"InlineQueryResultArticle", "Type of the result, must be article", []string{"article"}},
+		{"InlineQueryResultPhoto", "Type of the result, must be photo", []string{"photo"}},
+		{"InlineQueryResultMpeg4Gif", "Type of the result, must be mpeg4_gif", []string{"mpeg4_gif"}},
+		{"BotCommandScopeAllPrivateChats", "Scope type, must be all_private_chats", []string{"all_private_chats"}},
+		{"BotCommandScopeChat", "Scope type, must be chat", []string{"chat"}},
+		{"PassportElementErrorData", "Error source, must be data", []string{"data"}},
+		{"MenuButtonWebApp", "Type of the button, must be web_app", []string{"web_app"}},
+		{"InputProfilePhotoAnimated", "Type of the profile photo, must be animated", []string{"animated"}},
+		{"InputStoryContentVideo", "Type of the content, must be video", []string{"video"}},
+		{"InputPaidMediaPhoto", "Type of the media, must be photo", []string{"photo"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			require.Equal(t, tc.want, extractEnumValues("type", tc.desc))
+		})
+	}
+}
+
+func TestExtractEnumValues_ProseFalsePositives(t *testing.T) {
+	cases := []struct {
+		name string
+		desc string
+	}{
+		{"available_only_for", "Optional. Bot-specified invoice payload. Can be available only for “invoice_payment” transactions."},
+		{"must_be_sent", "If True, the message must be sent immediately."},
+		{"must_be_shown_above", "Optional. True, if the link preview must be shown above the message text"},
+		{"must_be_specified", "The identifiers must be specified in a strictly increasing order."},
+		{"must_be_paid", "The number of Telegram Stars that must be paid to send the sticker"},
+		{"must_be_one_of_numbers", "Number of months the Telegram Premium subscription will be active for the user; must be one of 3, 6, or 12"},
+		{"must_be_between", "Currently, price in Telegram Stars must be between 5 and 100000"},
+		{"must_be_a_pay_button", "If not empty, the first button must be a Pay button."},
+		{"must_be_repainted", "True, if the sticker must be repainted to a text color in messages"},
+		{"must_be_active", "the subscription must be active up to the end of the current subscription period"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			require.Nil(t, extractEnumValues("type", tc.desc))
+		})
+	}
+}
+
+func TestExtractEnumValues_CanonicalMustBeOneOfStillWorks(t *testing.T) {
+	desc := "Currently, must be one of “Markdown”, “MarkdownV2”, “HTML”"
+	got := extractEnumValues("parse_mode_kind", desc)
+	require.Equal(t, []string{"Markdown", "MarkdownV2", "HTML"}, got)
+}

dispatch/context.go

@@ -21,20 +21,45 @@ import (
 // Update is the raw update; payload-typed handlers also receive a
 // narrowed pointer to one of its sub-fields.
 //
-// Values is a per-update bag matchers populate. Conventional keys:
+// Command, CommandArgs and RegexMatch are populated by the router for
+// the matching route kind; they replace the previous "command",
+// "command_args" and "regex_match" entries in Values, which were the
+// only conventional keys. Values remains for user-defined custom keys.
 //
-//	"command":      string, the matched bot command (e.g. "/start")
-//	"command_args": string, everything after the command
-//	"regex_match":  []string, regex sub-matches when OnText matches
+// Command is the matched bot command (e.g. "/start"); empty when the
+// route is not a command match.
+//
+// CommandArgs is everything after the command; empty when no command
+// matched or the command had no trailing text.
+//
+// RegexMatch is the regex sub-matches when an OnText/OnCallback regex
+// route matched; nil otherwise.
+//
+// Values is lazily allocated for user-defined keys. Handlers that don't
+// write pay no allocation. Reads against a nil map return the zero
+// value. Writers must use Set instead of indexing the map directly.
 type Context struct {
-	Ctx    context.Context
-	Bot    *client.Bot
-	Update *api.Update
-	Values map[string]any
+	Ctx         context.Context
+	Bot         *client.Bot
+	Update      *api.Update
+	Command     string
+	CommandArgs string
+	RegexMatch  []string
+	Values      map[string]any
 }
 
 // NewContext constructs a Context. Used by Router internally; exposed for
 // custom test harnesses.
 func NewContext(ctx context.Context, b *client.Bot, u *api.Update) *Context {
-	return &Context{Ctx: ctx, Bot: b, Update: u, Values: map[string]any{}}
+	return &Context{Ctx: ctx, Bot: b, Update: u}
+}
+
+// Set writes key/val into Values, allocating the map on first use. Use
+// this instead of `c.Values[k] = v` so the no-write path stays
+// allocation-free.
+func (c *Context) Set(key string, val any) {
+	if c.Values == nil {
+		c.Values = make(map[string]any, 2)
+	}
+	c.Values[key] = val
 }

dispatch/groups.go

@@ -138,8 +138,8 @@ func (r *Router) runGroupHandlers(c *Context, m *api.Message, g int) (matched bo
 			if route.group != g || route.cmd != cmd {
 				continue
 			}
-			c.Values["command"] = cmd
-			c.Values["command_args"] = args
+			c.Command = cmd
+			c.CommandArgs = args
 			if err := route.handler(c, m); err != nil {
 				if errors.Is(err, ErrContinueGroups) {
 					continue
@@ -159,7 +159,7 @@ func (r *Router) runGroupHandlers(c *Context, m *api.Message, g int) (matched bo
 			if subs == nil {
 				continue
 			}
-			c.Values["regex_match"] = subs
+			c.RegexMatch = subs
 			if err := route.handler(c, m); err != nil {
 				if errors.Is(err, ErrContinueGroups) {
 					continue

dispatch/router.go

@@ -467,8 +467,8 @@ func (r *Router) handleMessage(c *Context, m *api.Message) error {
 	if cmd, args, ok := extractCommand(m); ok {
 		for _, route := range r.commands {
 			if route.cmd == cmd {
-				c.Values["command"] = cmd
-				c.Values["command_args"] = args
+				c.Command = cmd
+				c.CommandArgs = args
 				return route.handler(c, m)
 			}
 		}
@@ -477,7 +477,7 @@ func (r *Router) handleMessage(c *Context, m *api.Message) error {
 	if m.Text != "" {
 		for _, route := range r.texts {
 			if subs := route.re.FindStringSubmatch(m.Text); subs != nil {
-				c.Values["regex_match"] = subs
+				c.RegexMatch = subs
 				return route.handler(c, m)
 			}
 		}
@@ -495,7 +495,7 @@ func (r *Router) handleMessage(c *Context, m *api.Message) error {
 func (r *Router) handleCallback(c *Context, q *api.CallbackQuery) error {
 	for _, route := range r.callbacks {
 		if subs := route.re.FindStringSubmatch(q.Data); subs != nil {
-			c.Values["regex_match"] = subs
+			c.RegexMatch = subs
 			return route.handler(c, q)
 		}
 	}

dispatch/router_bench_test.go

@@ -0,0 +1,89 @@
+package dispatch
+
+import (
+	"context"
+	"testing"
+
+	"github.com/lukaszraczylo/go-telegram/api"
+	"github.com/lukaszraczylo/go-telegram/client"
+)
+
+func BenchmarkRouter_DispatchCommand(b *testing.B) {
+	r := New(client.New("t"))
+	r.OnCommand("/start", func(c *Context, m *api.Message) error { return nil })
+	u := cmdMessage("/start hello")
+	ctx := context.Background()
+	b.ReportAllocs()
+	for b.Loop() {
+		c := NewContext(ctx, r.bot, &u)
+		_ = r.dispatch(c, &u)
+	}
+}
+
+func BenchmarkRouter_DispatchTextRegex(b *testing.B) {
+	r := New(client.New("t"))
+	r.OnText("^hello.*", func(c *Context, m *api.Message) error { return nil })
+	u := api.Update{
+		UpdateID: 1,
+		Message: &api.Message{
+			MessageID: 1, Date: 0,
+			Chat: api.Chat{ID: 1, Type: api.ChatTypePrivate},
+			Text: "hello world",
+		},
+	}
+	ctx := context.Background()
+	b.ReportAllocs()
+	for b.Loop() {
+		c := NewContext(ctx, r.bot, &u)
+		_ = r.dispatch(c, &u)
+	}
+}
+
+func BenchmarkRouter_DispatchFilter(b *testing.B) {
+	r := New(client.New("t"))
+	r.OnMessageFilter(
+		func(m *api.Message) bool { return m != nil && m.Text == "ping" },
+		func(c *Context, m *api.Message) error { return nil },
+	)
+	u := api.Update{
+		UpdateID: 1,
+		Message: &api.Message{
+			MessageID: 1, Date: 0,
+			Chat: api.Chat{ID: 1, Type: api.ChatTypePrivate},
+			Text: "ping",
+		},
+	}
+	ctx := context.Background()
+	b.ReportAllocs()
+	for b.Loop() {
+		c := NewContext(ctx, r.bot, &u)
+		_ = r.dispatch(c, &u)
+	}
+}
+
+func BenchmarkRouter_NewContext(b *testing.B) {
+	bot := client.New("t")
+	u := &api.Update{UpdateID: 1}
+	ctx := context.Background()
+	b.ReportAllocs()
+	for b.Loop() {
+		_ = NewContext(ctx, bot, u)
+	}
+}
+
+func BenchmarkExtractCommand(b *testing.B) {
+	text := "/start@BotName hello world"
+	cmdLen := len("/start@BotName")
+	m := &api.Message{
+		MessageID: 1, Date: 0,
+		Chat: api.Chat{ID: 1, Type: api.ChatTypePrivate},
+		Text: text,
+		Entities: []api.MessageEntity{
+			{Type: api.MessageEntityTypeBotCommand, Offset: 0, Length: int64(cmdLen)},
+		},
+	}
+	b.ReportAllocs()
+	for b.Loop() {
+		_, _, _ = extractCommand(m)
+	}
+}

dispatch/router_test.go

@@ -52,7 +52,7 @@ func TestRouter_OnCommandMatches(t *testing.T) {
 	r := New(b)
 	hit := make(chan string, 1)
 	r.OnCommand("/start", func(c *Context, m *api.Message) error {
-		hit <- c.Values["command"].(string)
+		hit <- c.Command
 		return nil
 	})
 
@@ -82,7 +82,7 @@ func TestRouter_OnText(t *testing.T) {
 	r := New(client.New("t"))
 	hit := make(chan []string, 1)
 	r.OnText(`^hello (\w+)$`, func(c *Context, m *api.Message) error {
-		hit <- c.Values["regex_match"].([]string)
+		hit <- c.RegexMatch
 		return nil
 	})
 
@@ -164,10 +164,7 @@ func TestRouter_NonASCIICommand(t *testing.T) {
 	r := New(client.New("t"))
 	hit := make(chan [2]string, 1)
 	r.OnCommand("/старт", func(c *Context, m *api.Message) error {
-		hit <- [2]string{
-			c.Values["command"].(string),
-			c.Values["command_args"].(string),
-		}
+		hit <- [2]string{c.Command, c.CommandArgs}
 		return nil
 	})
 
@@ -180,16 +177,15 @@ func TestRouter_NonASCIICommand(t *testing.T) {
 	require.Equal(t, "аргумент", got[1])
 }
 
-// TestRouter_CommandValuesNotLeakedOnNoMatch verifies that c.Values["command"]
-// is not set when a command entity is present but no route matches, so a
+// TestRouter_CommandValuesNotLeakedOnNoMatch verifies that c.Command is
+// empty when a command entity is present but no route matches, so a
 // subsequent text handler doesn't see stale values.
 func TestRouter_CommandValuesNotLeakedOnNoMatch(t *testing.T) {
 	r := New(client.New("t"))
 	// Register a text handler that should fire as fallback.
 	leaked := make(chan bool, 1)
 	r.OnText(`.*`, func(c *Context, m *api.Message) error {
-		_, hasCmd := c.Values["command"]
-		leaked <- hasCmd
+		leaked <- c.Command != ""
 		return nil
 	})
 	// No OnCommand registered, so the command entity won't match any route.

docs/reference/client.md

@@ -80,7 +80,7 @@ var (
 ```
 
 <a name="Call"></a>
-## func [Call](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/call.go#L25>)
+## func [Call](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/call.go#L53>)
 
 ```go
 func Call[Req any, Resp any](ctx context.Context, b *Bot, method string, req Req) (Resp, error)
@@ -93,7 +93,7 @@ It is generic over both request and response types. Methods with no parameters m
 Call is exported because the api package \(which lives outside this one\) invokes it from generated method wrappers. User code should not normally call it directly — use the typed wrappers in package api instead.
 
 <a name="CallRaw"></a>
-## func [CallRaw](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/call.go#L74>)
+## func [CallRaw](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/call.go#L104>)
 
 ```go
 func CallRaw[Req any](ctx context.Context, b *Bot, method string, req Req) (json.RawMessage, error)
@@ -296,7 +296,7 @@ type Logger interface {
 ```
 
 <a name="MultipartFile"></a>
-## type [MultipartFile](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/multipart.go#L27-L31>)
+## type [MultipartFile](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/multipart.go#L28-L32>)
 
 MultipartFile describes a single file part in a multipart upload.
 

docs/reference/dispatch.md

@@ -13,6 +13,7 @@ Package dispatch provides a typed router for Telegram updates. It consumes any t
 - [Variables](<#variables>)
 - [type Context](<#Context>)
   - [func NewContext\(ctx context.Context, b \*client.Bot, u \*api.Update\) \*Context](<#NewContext>)
+  - [func \(c \*Context\) Set\(key string, val any\)](<#Context.Set>)
 - [type Filter](<#Filter>)
   - [func All\[T any\]\(filters ...Filter\[T\]\) Filter\[T\]](<#All>)
   - [func Any\[T any\]\(filters ...Filter\[T\]\) Filter\[T\]](<#Any>)
@@ -90,7 +91,7 @@ var ErrEndGroups = errors.New("dispatch: end groups")
 ```
 
 <a name="Context"></a>
-## type [Context](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/context.go#L29-L34>)
+## type [Context](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/context.go#L41-L49>)
 
 Context bundles the per\-update state every handler receives.
 
@@ -100,25 +101,30 @@ Bot is the API client. Handlers reply by calling api.SendMessage\(c.Ctx, c.Bot,
 
 Update is the raw update; payload\-typed handlers also receive a narrowed pointer to one of its sub\-fields.
 
-Values is a per\-update bag matchers populate. Conventional keys:
+Command, CommandArgs and RegexMatch are populated by the router for the matching route kind; they replace the previous "command", "command\_args" and "regex\_match" entries in Values, which were the only conventional keys. Values remains for user\-defined custom keys.
 
-```
-"command":      string, the matched bot command (e.g. "/start")
-"command_args": string, everything after the command
-"regex_match":  []string, regex sub-matches when OnText matches
-```
+Command is the matched bot command \(e.g. "/start"\); empty when the route is not a command match.
+
+CommandArgs is everything after the command; empty when no command matched or the command had no trailing text.
+
+RegexMatch is the regex sub\-matches when an OnText/OnCallback regex route matched; nil otherwise.
+
+Values is lazily allocated for user\-defined keys. Handlers that don't write pay no allocation. Reads against a nil map return the zero value. Writers must use Set instead of indexing the map directly.
 
 ```go
 type Context struct {
-    Ctx    context.Context
-    Bot    *client.Bot
-    Update *api.Update
-    Values map[string]any
+    Ctx         context.Context
+    Bot         *client.Bot
+    Update      *api.Update
+    Command     string
+    CommandArgs string
+    RegexMatch  []string
+    Values      map[string]any
 }
 ```
 
 <a name="NewContext"></a>
-### func [NewContext](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/context.go#L38>)
+### func [NewContext](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/context.go#L53>)
 
 ```go
 func NewContext(ctx context.Context, b *client.Bot, u *api.Update) *Context
@@ -126,6 +132,15 @@ func NewContext(ctx context.Context, b *client.Bot, u *api.Update) *Context
 
 NewContext constructs a Context. Used by Router internally; exposed for custom test harnesses.
 
+<a name="Context.Set"></a>
+### func \(\*Context\) [Set](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/context.go#L60>)
+
+```go
+func (c *Context) Set(key string, val any)
+```
+
+Set writes key/val into Values, allocating the map on first use. Use this instead of \`c.Values\[k\] = v\` so the no\-write path stays allocation\-free.
+
 <a name="Filter"></a>
 ## type [Filter](<https://github.com/lukaszraczylo/go-telegram/blob/main/dispatch/filter.go#L9>)
 

docs/reference/transport.md

@@ -113,7 +113,7 @@ func (p *LongPoller) Run(ctx context.Context) error
 Run implements Updater. It blocks until ctx is cancelled, Stop is called, or a fatal error occurs \(e.g. unauthorized\). See LongPoller for at\-least\-once delivery semantics on shutdown.
 
 <a name="LongPoller.Stop"></a>
-### func \(\*LongPoller\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L126>)
+### func \(\*LongPoller\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L122>)
 
 ```go
 func (p *LongPoller) Stop(ctx context.Context) error
@@ -154,7 +154,7 @@ type Updater interface {
 ```
 
 <a name="WebhookOption"></a>
-## type [WebhookOption](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L38>)
+## type [WebhookOption](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L57>)
 
 WebhookOption configures a WebhookServer at construction time.
 
@@ -163,7 +163,7 @@ type WebhookOption func(*webhookOptions)
 ```
 
 <a name="WithBufferSize"></a>
-### func [WithBufferSize](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L46>)
+### func [WithBufferSize](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L65>)
 
 ```go
 func WithBufferSize(n int) WebhookOption
@@ -172,7 +172,7 @@ func WithBufferSize(n int) WebhookOption
 WithBufferSize sets the size of the updates channel buffer. Default is 64.
 
 <a name="WebhookServer"></a>
-## type [WebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L24-L35>)
+## type [WebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L43-L54>)
 
 WebhookServer implements Updater by exposing an http.Handler that receives updates from Telegram. It can be mounted on the user's own HTTP server \(via ServeHTTP\) or run standalone \(via ListenAndServe\).
 
@@ -185,7 +185,7 @@ type WebhookServer struct {
 ```
 
 <a name="NewWebhookServer"></a>
-### func [NewWebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L52>)
+### func [NewWebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L71>)
 
 ```go
 func NewWebhookServer(b *client.Bot, opts ...WebhookOption) *WebhookServer
@@ -194,7 +194,7 @@ func NewWebhookServer(b *client.Bot, opts ...WebhookOption) *WebhookServer
 NewWebhookServer constructs a WebhookServer with default buffer size \(64\). Use WithBufferSize to override.
 
 <a name="WebhookServer.ListenAndServe"></a>
-### func \(\*WebhookServer\) [ListenAndServe](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L150>)
+### func \(\*WebhookServer\) [ListenAndServe](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L168>)
 
 ```go
 func (w *WebhookServer) ListenAndServe(ctx context.Context, addr string) error
@@ -203,7 +203,7 @@ func (w *WebhookServer) ListenAndServe(ctx context.Context, addr string) error
 ListenAndServe starts an HTTP server on addr and blocks until Stop is called \(which triggers Shutdown with the caller's context\) or the server returns an error other than http.ErrServerClosed. Callers must invoke Stop\(ctx\) to cleanly shut down the server; the ctx passed here is only used as the server's base context for incoming requests.
 
 <a name="WebhookServer.Run"></a>
-### func \(\*WebhookServer\) [Run](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L71>)
+### func \(\*WebhookServer\) [Run](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L90>)
 
 ```go
 func (w *WebhookServer) Run(ctx context.Context) error
@@ -212,7 +212,7 @@ func (w *WebhookServer) Run(ctx context.Context) error
 Run implements Updater. It blocks until Stop is called or ctx is cancelled. If the server has not been started via ListenAndServe, Run only watches for shutdown — the user is expected to mount ServeHTTP on their own router.
 
 <a name="WebhookServer.ServeHTTP"></a>
-### func \(\*WebhookServer\) [ServeHTTP](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L97>)
+### func \(\*WebhookServer\) [ServeHTTP](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L116>)
 
 ```go
 func (w *WebhookServer) ServeHTTP(rw http.ResponseWriter, r *http.Request)
@@ -221,7 +221,7 @@ func (w *WebhookServer) ServeHTTP(rw http.ResponseWriter, r *http.Request)
 ServeHTTP implements http.Handler. Telegram POSTs each update as JSON to this endpoint. Non\-POST requests get 405; bad bodies get 400; secret token mismatches get 401.
 
 <a name="WebhookServer.Stop"></a>
-### func \(\*WebhookServer\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L83>)
+### func \(\*WebhookServer\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L102>)
 
 ```go
 func (w *WebhookServer) Stop(ctx context.Context) error
@@ -230,7 +230,7 @@ func (w *WebhookServer) Stop(ctx context.Context) error
 Stop implements Updater.
 
 <a name="WebhookServer.Updates"></a>
-### func \(\*WebhookServer\) [Updates](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L65>)
+### func \(\*WebhookServer\) [Updates](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L84>)
 
 ```go
 func (w *WebhookServer) Updates() <-chan api.Update

examples/callback/handlers.go

@@ -21,7 +21,7 @@ func handleStart(c *dispatch.Context, m *api.Message) error {
 }
 
 func handleCallback(c *dispatch.Context, q *api.CallbackQuery) error {
-	groups := c.Values["regex_match"].([]string)
+	groups := c.RegexMatch
 	current, _ := strconv.Atoi(groups[1])
 	if groups[2] == "inc" {
 		current++

examples/callback/handlers_test.go

@@ -42,7 +42,7 @@ const (
 func makeCtx(bot *client.Bot, upd *api.Update, extra map[string]any) *dispatch.Context {
 	c := dispatch.NewContext(context.Background(), bot, upd)
 	for k, v := range extra {
-		c.Values[k] = v
+		c.Set(k, v)
 	}
 	return c
 }
@@ -82,7 +82,9 @@ func TestHandleStart_SendsInitialKeyboard(t *testing.T) {
 
 func callbackCtx(bot *client.Bot, q *api.CallbackQuery, groups []string) *dispatch.Context {
 	upd := &api.Update{UpdateID: 1, CallbackQuery: q}
-	return makeCtx(bot, upd, map[string]any{"regex_match": groups})
+	c := makeCtx(bot, upd, nil)
+	c.RegexMatch = groups
+	return c
 }
 
 func callbackQuery(data string, msgID int64, chatID int64) *api.CallbackQuery {

examples/pagination/main.go

@@ -111,8 +111,7 @@ func main() {
 
 	// page:<n> callbacks — edit message in-place.
 	router.OnCallback(`^page:(\d+)$`, func(c *dispatch.Context, q *api.CallbackQuery) error {
-		groups := c.Values["regex_match"].([]string)
-		page, _ := strconv.Atoi(groups[1])
+		page, _ := strconv.Atoi(c.RegexMatch[1])
 
 		// Acknowledge the tap first.
 		_, _ = api.AnswerCallbackQuery(c.Ctx, c.Bot, &api.AnswerCallbackQueryParams{

internal/spec/api.json

@@ -10529,7 +10529,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be default"
+          "doc": "Scope type, must be default",
+          "enum_values": [
+            "default"
+          ]
         }
       ]
     },
@@ -10545,7 +10548,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be all_private_chats"
+          "doc": "Scope type, must be all_private_chats",
+          "enum_values": [
+            "all_private_chats"
+          ]
         }
       ]
     },
@@ -10561,7 +10567,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be all_group_chats"
+          "doc": "Scope type, must be all_group_chats",
+          "enum_values": [
+            "all_group_chats"
+          ]
         }
       ]
     },
@@ -10577,7 +10586,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be all_chat_administrators"
+          "doc": "Scope type, must be all_chat_administrators",
+          "enum_values": [
+            "all_chat_administrators"
+          ]
         }
       ]
     },
@@ -10593,7 +10605,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be chat"
+          "doc": "Scope type, must be chat",
+          "enum_values": [
+            "chat"
+          ]
         },
         {
           "name": "ChatID",
@@ -10622,7 +10637,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be chat_administrators"
+          "doc": "Scope type, must be chat_administrators",
+          "enum_values": [
+            "chat_administrators"
+          ]
         },
         {
           "name": "ChatID",
@@ -10651,7 +10669,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Scope type, must be chat_member"
+          "doc": "Scope type, must be chat_member",
+          "enum_values": [
+            "chat_member"
+          ]
         },
         {
           "name": "ChatID",
@@ -10747,7 +10768,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the button, must be commands"
+          "doc": "Type of the button, must be commands",
+          "enum_values": [
+            "commands"
+          ]
         }
       ]
     },
@@ -10763,7 +10787,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the button, must be web_app"
+          "doc": "Type of the button, must be web_app",
+          "enum_values": [
+            "web_app"
+          ]
         },
         {
           "name": "Text",
@@ -10799,7 +10826,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the button, must be default"
+          "doc": "Type of the button, must be default",
+          "enum_values": [
+            "default"
+          ]
         }
       ]
     },
@@ -11451,7 +11481,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be animation"
+          "doc": "Type of the result, must be animation",
+          "enum_values": [
+            "animation"
+          ]
         },
         {
           "name": "Media",
@@ -11566,7 +11599,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be audio"
+          "doc": "Type of the result, must be audio",
+          "enum_values": [
+            "audio"
+          ]
         },
         {
           "name": "Media",
@@ -11663,7 +11699,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be document"
+          "doc": "Type of the result, must be document",
+          "enum_values": [
+            "document"
+          ]
         },
         {
           "name": "Media",
@@ -11742,7 +11781,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be live_photo"
+          "doc": "Type of the result, must be live_photo",
+          "enum_values": [
+            "live_photo"
+          ]
         },
         {
           "name": "Media",
@@ -11831,7 +11873,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be location"
+          "doc": "Type of the result, must be location",
+          "enum_values": [
+            "location"
+          ]
         },
         {
           "name": "Latitude",
@@ -11876,7 +11921,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be photo"
+          "doc": "Type of the result, must be photo",
+          "enum_values": [
+            "photo"
+          ]
         },
         {
           "name": "Media",
@@ -11955,7 +12003,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be sticker"
+          "doc": "Type of the result, must be sticker",
+          "enum_values": [
+            "sticker"
+          ]
         },
         {
           "name": "Media",
@@ -11990,7 +12041,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be venue"
+          "doc": "Type of the result, must be venue",
+          "enum_values": [
+            "venue"
+          ]
         },
         {
           "name": "Latitude",
@@ -12082,7 +12136,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be video"
+          "doc": "Type of the result, must be video",
+          "enum_values": [
+            "video"
+          ]
         },
         {
           "name": "Media",
@@ -12237,7 +12294,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the media, must be live_photo"
+          "doc": "Type of the media, must be live_photo",
+          "enum_values": [
+            "live_photo"
+          ]
         },
         {
           "name": "Media",
@@ -12273,7 +12333,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the media, must be photo"
+          "doc": "Type of the media, must be photo",
+          "enum_values": [
+            "photo"
+          ]
         },
         {
           "name": "Media",
@@ -12299,7 +12362,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the media, must be video"
+          "doc": "Type of the media, must be video",
+          "enum_values": [
+            "video"
+          ]
         },
         {
           "name": "Media",
@@ -12396,7 +12462,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the profile photo, must be static"
+          "doc": "Type of the profile photo, must be static",
+          "enum_values": [
+            "static"
+          ]
         },
         {
           "name": "Photo",
@@ -12422,7 +12491,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the profile photo, must be animated"
+          "doc": "Type of the profile photo, must be animated",
+          "enum_values": [
+            "animated"
+          ]
         },
         {
           "name": "Animation",
@@ -12465,7 +12537,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the content, must be photo"
+          "doc": "Type of the content, must be photo",
+          "enum_values": [
+            "photo"
+          ]
         },
         {
           "name": "Photo",
@@ -12491,7 +12566,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the content, must be video"
+          "doc": "Type of the content, must be video",
+          "enum_values": [
+            "video"
+          ]
         },
         {
           "name": "Video",
@@ -13008,7 +13086,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be article"
+          "doc": "Type of the result, must be article",
+          "enum_values": [
+            "article"
+          ]
         },
         {
           "name": "ID",
@@ -13108,7 +13189,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be photo"
+          "doc": "Type of the result, must be photo",
+          "enum_values": [
+            "photo"
+          ]
         },
         {
           "name": "ID",
@@ -13252,7 +13336,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be gif"
+          "doc": "Type of the result, must be gif",
+          "enum_values": [
+            "gif"
+          ]
         },
         {
           "name": "ID",
@@ -13410,7 +13497,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be mpeg4_gif"
+          "doc": "Type of the result, must be mpeg4_gif",
+          "enum_values": [
+            "mpeg4_gif"
+          ]
         },
         {
           "name": "ID",
@@ -13568,7 +13658,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be video"
+          "doc": "Type of the result, must be video",
+          "enum_values": [
+            "video"
+          ]
         },
         {
           "name": "ID",
@@ -13732,7 +13825,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be audio"
+          "doc": "Type of the result, must be audio",
+          "enum_values": [
+            "audio"
+          ]
         },
         {
           "name": "ID",
@@ -13849,7 +13945,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be voice"
+          "doc": "Type of the result, must be voice",
+          "enum_values": [
+            "voice"
+          ]
         },
         {
           "name": "ID",
@@ -13957,7 +14056,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be document"
+          "doc": "Type of the result, must be document",
+          "enum_values": [
+            "document"
+          ]
         },
         {
           "name": "ID",
@@ -14106,7 +14208,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be location"
+          "doc": "Type of the result, must be location",
+          "enum_values": [
+            "location"
+          ]
         },
         {
           "name": "ID",
@@ -14243,7 +14348,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be venue"
+          "doc": "Type of the result, must be venue",
+          "enum_values": [
+            "venue"
+          ]
         },
         {
           "name": "ID",
@@ -14390,7 +14498,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be contact"
+          "doc": "Type of the result, must be contact",
+          "enum_values": [
+            "contact"
+          ]
         },
         {
           "name": "ID",
@@ -14499,7 +14610,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be game"
+          "doc": "Type of the result, must be game",
+          "enum_values": [
+            "game"
+          ]
         },
         {
           "name": "ID",
@@ -14544,7 +14658,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be photo"
+          "doc": "Type of the result, must be photo",
+          "enum_values": [
+            "photo"
+          ]
         },
         {
           "name": "ID",
@@ -14660,7 +14777,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be gif"
+          "doc": "Type of the result, must be gif",
+          "enum_values": [
+            "gif"
+          ]
         },
         {
           "name": "ID",
@@ -14767,7 +14887,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be mpeg4_gif"
+          "doc": "Type of the result, must be mpeg4_gif",
+          "enum_values": [
+            "mpeg4_gif"
+          ]
         },
         {
           "name": "ID",
@@ -14874,7 +14997,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be sticker"
+          "doc": "Type of the result, must be sticker",
+          "enum_values": [
+            "sticker"
+          ]
         },
         {
           "name": "ID",
@@ -14928,7 +15054,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be document"
+          "doc": "Type of the result, must be document",
+          "enum_values": [
+            "document"
+          ]
         },
         {
           "name": "ID",
@@ -15036,7 +15165,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be video"
+          "doc": "Type of the result, must be video",
+          "enum_values": [
+            "video"
+          ]
         },
         {
           "name": "ID",
@@ -15153,7 +15285,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be voice"
+          "doc": "Type of the result, must be voice",
+          "enum_values": [
+            "voice"
+          ]
         },
         {
           "name": "ID",
@@ -15252,7 +15387,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Type of the result, must be audio"
+          "doc": "Type of the result, must be audio",
+          "enum_values": [
+            "audio"
+          ]
         },
         {
           "name": "ID",
@@ -17138,7 +17276,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be data"
+          "doc": "Error source, must be data",
+          "enum_values": [
+            "data"
+          ]
         },
         {
           "name": "Type",
@@ -17202,7 +17343,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be front_side"
+          "doc": "Error source, must be front_side",
+          "enum_values": [
+            "front_side"
+          ]
         },
         {
           "name": "Type",
@@ -17254,7 +17398,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be reverse_side"
+          "doc": "Error source, must be reverse_side",
+          "enum_values": [
+            "reverse_side"
+          ]
         },
         {
           "name": "Type",
@@ -17304,7 +17451,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be selfie"
+          "doc": "Error source, must be selfie",
+          "enum_values": [
+            "selfie"
+          ]
         },
         {
           "name": "Type",
@@ -17356,7 +17506,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be file"
+          "doc": "Error source, must be file",
+          "enum_values": [
+            "file"
+          ]
         },
         {
           "name": "Type",
@@ -17409,7 +17562,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be files"
+          "doc": "Error source, must be files",
+          "enum_values": [
+            "files"
+          ]
         },
         {
           "name": "Type",
@@ -17465,7 +17621,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be translation_file"
+          "doc": "Error source, must be translation_file",
+          "enum_values": [
+            "translation_file"
+          ]
         },
         {
           "name": "Type",
@@ -17522,7 +17681,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be translation_files"
+          "doc": "Error source, must be translation_files",
+          "enum_values": [
+            "translation_files"
+          ]
         },
         {
           "name": "Type",
@@ -17582,7 +17744,10 @@
             "name": "string"
           },
           "required": true,
-          "doc": "Error source, must be unspecified"
+          "doc": "Error source, must be unspecified",
+          "enum_values": [
+            "unspecified"
+          ]
         },
         {
           "name": "Type",

transport/longpoll.go

@@ -72,11 +72,7 @@ func (p *LongPoller) Run(ctx context.Context) error {
 			params.Timeout = &to
 		}
 		if len(p.AllowedTypes) > 0 {
-			allowed := make([]string, len(p.AllowedTypes))
-			for i, t := range p.AllowedTypes {
-				allowed[i] = string(t)
-			}
-			params.AllowedUpdates = allowed
+			params.AllowedUpdates = p.AllowedTypes
 		}
 		ups, err := api.GetUpdates(ctx, p.Bot, params)
 		if err != nil {

transport/webhook.go

@@ -6,6 +6,7 @@
 package transport
 
 import (
+	"bytes"
 	"context"
 	"crypto/subtle"
 	"errors"
@@ -18,6 +19,24 @@ import (
 	"github.com/lukaszraczylo/go-telegram/client"
 )
 
+// webhookBufPool reuses *bytes.Buffer for incoming webhook bodies.
+// Webhook payloads are typically a single Telegram Update (commonly
+// 1-8 KiB), so a buffer that has grown once will satisfy most
+// subsequent requests with no additional allocation.
+var webhookBufPool = sync.Pool{New: func() any { return new(bytes.Buffer) }}
+
+// maxWebhookBufCap caps the buffer size returned to webhookBufPool so
+// a rare oversized update doesn't permanently bloat the pool. Buffers
+// larger than this are dropped on the floor.
+const maxWebhookBufCap = 256 * 1024
+
+func putWebhookBuf(buf *bytes.Buffer) {
+	if buf.Cap() > maxWebhookBufCap {
+		return
+	}
+	webhookBufPool.Put(buf)
+}
+
 // WebhookServer implements Updater by exposing an http.Handler that
 // receives updates from Telegram. It can be mounted on the user's own
 // HTTP server (via ServeHTTP) or run standalone (via ListenAndServe).
@@ -108,28 +127,27 @@ func (w *WebhookServer) ServeHTTP(rw http.ResponseWriter, r *http.Request) {
 	}
 	w.handlers.Add(1)
 	defer w.handlers.Done()
+
+	const maxBody = 1 << 20 // 1 MiB cap on body
+	r.Body = http.MaxBytesReader(rw, r.Body, maxBody)
 	defer func() { _ = r.Body.Close() }()
 
-	const max = 1 << 20 // 1 MiB cap on body
-	buf := make([]byte, 0, 1024)
-	tmp := make([]byte, 4096)
-	for {
-		n, err := r.Body.Read(tmp)
-		if n > 0 {
-			buf = append(buf, tmp[:n]...)
-			if len(buf) > max {
-				rw.WriteHeader(http.StatusRequestEntityTooLarge)
-				return
-			}
-		}
-		if errors.Is(err, http.ErrBodyReadAfterClose) || err != nil {
-			break
+	buf := webhookBufPool.Get().(*bytes.Buffer)
+	buf.Reset()
+	defer putWebhookBuf(buf)
+	if _, err := buf.ReadFrom(r.Body); err != nil {
+		var maxErr *http.MaxBytesError
+		if errors.As(err, &maxErr) {
+			rw.WriteHeader(http.StatusRequestEntityTooLarge)
+			return
 		}
+		rw.WriteHeader(http.StatusBadRequest)
+		return
 	}
 
 	var u api.Update
 	codec := w.Bot.Codec()
-	if err := codec.Unmarshal(buf, &u); err != nil {
+	if err := codec.Unmarshal(buf.Bytes(), &u); err != nil {
 		rw.WriteHeader(http.StatusBadRequest)
 		return
 	}

transport/webhook_bench_test.go

@@ -0,0 +1,39 @@
+package transport
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/lukaszraczylo/go-telegram/client"
+)
+
+const benchUpdateBody = `{"update_id":12345,"message":{"message_id":1,"date":1700000000,"chat":{"id":42,"type":"private"},"from":{"id":42,"is_bot":false,"first_name":"User"},"text":"hello world"}}`
+
+func BenchmarkWebhook_ServeHTTP(b *testing.B) {
+	w := NewWebhookServer(client.New("t"), WithBufferSize(1024))
+	body := []byte(benchUpdateBody)
+
+	done := make(chan struct{})
+	go func() {
+		for {
+			select {
+			case <-w.Updates():
+			case <-done:
+				return
+			}
+		}
+	}()
+	defer close(done)
+
+	b.ReportAllocs()
+	for b.Loop() {
+		req := httptest.NewRequest(http.MethodPost, "/", bytes.NewReader(body))
+		rec := httptest.NewRecorder()
+		w.ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			b.Fatalf("status %d", rec.Code)
+		}
+	}
+}