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/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.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

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.

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/api.md

@@ -289,6 +289,7 @@ Package api contains the Telegram Bot API object types and method wrappers, gene
 - [type DeleteStoryParams](<#DeleteStoryParams>)
 - [type DeleteWebhookParams](<#DeleteWebhookParams>)
 - [type Dice](<#Dice>)
+- [type DiceEmoji](<#DiceEmoji>)
 - [type DirectMessagePriceChanged](<#DirectMessagePriceChanged>)
 - [type DirectMessagesTopic](<#DirectMessagesTopic>)
 - [type Document](<#Document>)
@@ -651,6 +652,7 @@ Package api contains the Telegram Bot API object types and method wrappers, gene
 - [type ProximityAlertTriggered](<#ProximityAlertTriggered>)
 - [type ReactionCount](<#ReactionCount>)
   - [func \(m \*ReactionCount\) UnmarshalJSON\(data \[\]byte\) error](<#ReactionCount.UnmarshalJSON>)
+- [type ReactionEmoji](<#ReactionEmoji>)
 - [type ReactionType](<#ReactionType>)
   - [func UnmarshalReactionType\(data \[\]byte\) \(ReactionType, error\)](<#UnmarshalReactionType>)
 - [type ReactionTypeCustomEmoji](<#ReactionTypeCustomEmoji>)
@@ -4884,6 +4886,28 @@ type Dice struct {
 }
 ```
 
+<a name="DiceEmoji"></a>
+## type [DiceEmoji](<https://github.com/lukaszraczylo/go-telegram/blob/main/api/enums.go#L42>)
+
+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.
+
+```go
+type DiceEmoji string
+```
+
+<a name="DiceEmojiDice"></a>
+
+```go
+const (
+    DiceEmojiDice        DiceEmoji = "🎲"
+    DiceEmojiDart        DiceEmoji = "🎯"
+    DiceEmojiBasketball  DiceEmoji = "🏀"
+    DiceEmojiFootball    DiceEmoji = "⚽"
+    DiceEmojiBowling     DiceEmoji = "🎳"
+    DiceEmojiSlotMachine DiceEmoji = "🎰"
+)
+```
+
 <a name="DirectMessagePriceChanged"></a>
 ## type [DirectMessagePriceChanged](<https://github.com/lukaszraczylo/go-telegram/blob/main/api/types.gen.go#L2179-L2184>)
 
@@ -6096,7 +6120,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"`
 }
 ```
 
@@ -11289,6 +11313,95 @@ func (m *ReactionCount) UnmarshalJSON(data []byte) error
 
 UnmarshalJSON decodes ReactionCount by dispatching union\-typed fields \(Type\) through their concrete UnmarshalXxx helpers.
 
+<a name="ReactionEmoji"></a>
+## type [ReactionEmoji](<https://github.com/lukaszraczylo/go-telegram/blob/main/api/enums.go#L62>)
+
+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.
+
+```go
+type ReactionEmoji string
+```
+
+<a name="ReactionEmojiHeart"></a>
+
+```go
+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 = "😡"
+)
+```
+
 <a name="ReactionType"></a>
 ## type [ReactionType](<https://github.com/lukaszraczylo/go-telegram/blob/main/api/types.gen.go#L3433>)
 
@@ -11348,7 +11461,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"`
 }
 ```
 
@@ -12150,7 +12263,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
@@ -13887,7 +14000,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.
@@ -15953,7 +16066,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"`
 }
 ```
 

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{

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)
+		}
+	}
+}