v1.0.0 beta 11

v1.0.0 beta 10
v1.0.0 beta 9
2026-03-06 12:46:30 +03:00 · 2026-03-06 12:12:16 +03:00 · 2026-03-06 11:59:17 +03:00 · 2026-03-02 17:06:13 +03:00 · 2026-03-02 16:49:00 +03:00 · 2026-03-02 00:08:26 +03:00
26 changed files with 1044 additions and 477 deletions
--- a/15
+++ b/15
@@ -0,0 +1,15 @@
+# Проверка наличия golangci-lint
+GO_LINT := $(shell command -v golangci-lint 2>/dev/null)
+
+# Цель: запуск всех проверок кода
+check:
+	@echo "🔍 Running code checks..."
+	@go mod tidy -v
+	@go vet ./...
+	@if [ -n "$(GO_LINT)" ]; then \
+		echo "✅ golangci-lint found, running..." && \
+		golangci-lint run --timeout=5m --verbose; \
+	else \
+		echo "⚠️  golangci-lint not installed. Install with: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.57.2"; \
+	fi
+	@go test -race -v ./... 2>/dev/null || echo "⚠️  Tests skipped or failed (run manually with 'go test -race ./...')"
--- a/bot.go
+++ b/bot.go
@@ -11,9 +11,9 @@ import (

 	"git.nix13.pw/scuroneko/extypes"
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
 	"github.com/alitto/pond/v2"
-	"golang.org/x/time/rate"
 )

 type BotOpts struct {
@@ -74,6 +74,7 @@ type Bot[T DbContext] struct {
 	token         string
 	debug         bool
 	errorTemplate string
+	username      string

 	logger        *slog.Logger
 	RequestLogger *slog.Logger
@@ -99,9 +100,9 @@ type Bot[T DbContext] struct {
 func NewBot[T any](opts *BotOpts) *Bot[T] {
 	updateQueue := make(chan *tgapi.Update, 512)

-	var limiter *rate.Limiter
+	var limiter *utils.RateLimiter
 	if opts.RateLimit > 0 {
-		limiter = rate.NewLimiter(rate.Limit(opts.RateLimit), opts.RateLimit)
+		limiter = utils.NewRateLimiter()
 	}

 	apiOpts := tgapi.NewAPIOpts(opts.Token).SetAPIUrl(opts.APIUrl).UseTestServer(opts.UseTestServer).SetLimiter(limiter)
@@ -140,6 +141,10 @@ func NewBot[T any](opts *BotOpts) *Bot[T] {
 		_ = bot.Close()
 		bot.logger.Fatal(err)
 	}
+	bot.username = Val(u.Username, "")
+	if bot.username == "" {
+		bot.logger.Warn("Can't get bot username. Named command wouldn't work!")
+	}
 	bot.logger.Infof("Authorized as %s\n", u.FirstName)

 	return bot
--- a/cmd_generator.go
+++ b/cmd_generator.go
@@ -16,7 +16,7 @@ func generateBotCommand[T any](cmd Command[T]) tgapi.BotCommand {
 	var descArgs []string
 	for _, a := range cmd.args {
 		if a.required {
-			descArgs = append(descArgs, fmt.Sprintf("%s", a.text))
+			descArgs = append(descArgs, a.text)
 		} else {
 			descArgs = append(descArgs, fmt.Sprintf("[%s]", a.text))
 		}
--- a/drafts.go
+++ b/drafts.go
@@ -1,11 +1,11 @@
 package laniakea

 import (
-	"math"
 	"math/rand/v2"
 	"sync/atomic"

 	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.nix13.pw/scuroneko/laniakea/utils"
 )

 type draftIdGenerator interface {
@@ -17,22 +17,22 @@ type RandomDraftIdGenerator struct {
 }

 func (g *RandomDraftIdGenerator) Next() uint64 {
-	return rand.Uint64N(math.MaxUint64)
+	return rand.Uint64()
 }

 type LinearDraftIdGenerator struct {
 	draftIdGenerator
-	lastId uint64
+	lastId atomic.Uint64
 }

 func (g *LinearDraftIdGenerator) Next() uint64 {
-	return atomic.AddUint64(&g.lastId, 1)
+	return g.lastId.Add(1)
 }

 type DraftProvider struct {
 	api *tgapi.API

-	chatID          int
+	chatID          int64
 	messageThreadID int
 	parseMode       tgapi.ParseMode
 	entities        []tgapi.MessageEntity
@@ -42,8 +42,9 @@ type DraftProvider struct {
 }
 type Draft struct {
 	api      *tgapi.API
+	provider *DraftProvider

-	chatID          int
+	chatID          int64
 	messageThreadID int
 	parseMode       tgapi.ParseMode
 	entities        []tgapi.MessageEntity
@@ -55,25 +56,42 @@ type Draft struct {
 func NewRandomDraftProvider(api *tgapi.API) *DraftProvider {
 	return &DraftProvider{
 		api: api, generator: &RandomDraftIdGenerator{},
+		parseMode: tgapi.ParseMDV2,
 		drafts:    make(map[uint64]*Draft),
 	}
 }
 func NewLinearDraftProvider(api *tgapi.API, startValue uint64) *DraftProvider {
+	g := &LinearDraftIdGenerator{}
+	g.lastId.Store(startValue)
 	return &DraftProvider{
 		api:       api,
-		generator: &LinearDraftIdGenerator{lastId: startValue},
+		generator: g,
 		drafts:    make(map[uint64]*Draft),
 	}
 }
 func (d *DraftProvider) NewDraft() *Draft {
 	id := d.generator.Next()
-	draft := &Draft{d.api, d.chatID, d.messageThreadID, d.parseMode, d.entities, id, ""}
+	entitiesCopy := make([]tgapi.MessageEntity, 0)
+	copy(entitiesCopy, d.entities)
+	draft := &Draft{
+		api:             d.api,
+		provider:        d,
+		chatID:          d.chatID,
+		messageThreadID: d.messageThreadID,
+		parseMode:       d.parseMode,
+		entities:        entitiesCopy,
+		ID:              id,
+		Message:         "",
+	}
 	d.drafts[id] = draft
 	return draft
 }
-
-func (d *Draft) Push(newText string) error {
-	d.Message += newText
+func (d *Draft) push(text string, escapeMd bool) error {
+	if escapeMd {
+		text += utils.EscapeMarkdownV2(text)
+	} else {
+		text += text
+	}
 	params := tgapi.SendMessageDraftP{
 		ChatID:    d.chatID,
 		DraftID:   d.ID,
@@ -87,3 +105,35 @@ func (d *Draft) Push(newText string) error {
 	_, err := d.api.SendMessageDraft(params)
 	return err
 }
+
+func (d *Draft) Push(text string) error {
+	return d.push(text, true)
+}
+func (d *Draft) PushMarkdown(text string) error {
+	return d.push(text, false)
+}
+
+func (d *Draft) Clear() {
+	d.Message = ""
+}
+func (d *Draft) Flush() error {
+	if d.Message == "" {
+		return nil
+	}
+
+	params := tgapi.SendMessageP{
+		ChatID:    d.chatID,
+		ParseMode: d.parseMode,
+		Entities:  d.entities,
+		Text:      d.Message,
+	}
+	if d.messageThreadID > 0 {
+		params.MessageThreadID = d.messageThreadID
+	}
+	_, err := d.api.SendMessage(params)
+	if err == nil {
+		d.Clear()
+		delete(d.provider.drafts, d.ID)
+	}
+	return err
+}
--- a/handler.go
+++ b/handler.go
@@ -49,34 +49,34 @@ func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) {
 	ctx.From = update.Message.From
 	ctx.Msg = update.Message

+	// Убираем префикс
 	text = strings.TrimSpace(text[len(prefix):])

-	for _, plugin := range bot.plugins {
-		for cmd := range plugin.commands {
-			if !strings.HasPrefix(text, cmd) {
-				continue
-			}
-			requestParts := strings.Split(text, " ")
-			cmdParts := strings.Split(cmd, " ")
-			isValid := true
-			for i, part := range cmdParts {
-				if part != requestParts[i] {
-					isValid = false
-					break
-				}
-			}
+	// Извлекаем команду как первое слово
+	spaceIndex := strings.Index(text, " ")
+	var cmd string
+	var args string

-			if !isValid {
-				continue
-			}
-
-			ctx.Text = strings.TrimSpace(text[len(cmd):])
-			if ctx.Text == "" {
-				ctx.Args = []string{}
+	if spaceIndex == -1 {
+		cmd = text
+		args = ""
 	} else {
-				ctx.Args = strings.Split(ctx.Text, " ")
+		cmd = text[:spaceIndex]
+		args = strings.TrimSpace(text[spaceIndex:])
 	}

+	if strings.Contains(cmd, "@") {
+		botUsername := bot.username
+		if botUsername != "" && strings.HasSuffix(cmd, "@"+botUsername) {
+			cmd = cmd[:len(cmd)-len("@"+botUsername)] // убираем @botname
+		}
+	}
+
+	// Ищем команду по точному совпадению
+	for _, plugin := range bot.plugins {
+		if _, exists := plugin.commands[cmd]; exists {
+			ctx.Text = args
+			ctx.Args = strings.Fields(args) // Убирает лишние пробелы
 			if !plugin.executeMiddlewares(ctx, bot.dbContext) {
 				return
 			}
--- a/msg_context.go
+++ b/msg_context.go
@@ -1,6 +1,7 @@
 package laniakea

 import (
+	"context"
 	"fmt"

 	"git.nix13.pw/scuroneko/laniakea/tgapi"
@@ -98,11 +99,14 @@ func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *An
 	return m.ctx.editPhotoText(m.MessageID, text, kb)
 }

-func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMessage {
+func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard, escapeMd bool) *AnswerMessage {
 	params := tgapi.SendMessageP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: tgapi.ParseMDV2,
+	}
+	if escapeMd {
+		params.Text = utils.EscapeMarkdownV2(text)
 	}
 	if keyboard != nil {
 		params.ReplyMarkup = keyboard.Get()
@@ -110,7 +114,15 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMess
 	if ctx.Msg.MessageThreadID > 0 {
 		params.MessageThreadID = ctx.Msg.MessageThreadID
 	}
+	if ctx.Msg.DirectMessageTopic != nil {
+		params.DirectMessagesTopicID = ctx.Msg.DirectMessageTopic.TopicID
+	}

+	cont := context.Background()
+	if err := ctx.Api.Limiter.Wait(cont, ctx.Msg.Chat.ID); err != nil {
+		ctx.botLogger.Errorln(err)
+		return nil
+	}
 	msg, err := ctx.Api.SendMessage(params)
 	if err != nil {
 		ctx.botLogger.Errorln(err)
@@ -120,23 +132,35 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMess
 		MessageID: msg.MessageID, ctx: ctx, IsMedia: false, Text: text,
 	}
 }
+func (ctx *MsgContext) AnswerMarkdown(text string) *AnswerMessage {
+	return ctx.answer(text, nil, false)
+}
 func (ctx *MsgContext) Answer(text string) *AnswerMessage {
-	return ctx.answer(text, nil)
+	return ctx.answer(text, nil, true)
+}
+func (ctx *MsgContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, false)
 }
 func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
-	return ctx.answer(fmt.Sprintf(template, args...), nil)
+	return ctx.answer(fmt.Sprintf(template, args...), nil, true)
+}
+func (ctx *MsgContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, keyboard, false)
 }
 func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answer(text, kb)
+	return ctx.answer(text, kb, true)
 }

-func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard, escapeMd bool) *AnswerMessage {
 	params := tgapi.SendPhotoP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Caption:   text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: tgapi.ParseMDV2,
 		Photo:     photoId,
 	}
+	if escapeMd {
+		params.Caption = utils.EscapeMarkdownV2(text)
+	}
 	if kb != nil {
 		params.ReplyMarkup = kb.Get()
 	}
@@ -156,10 +180,24 @@ func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *An
 	}
 }
 func (ctx *MsgContext) AnswerPhoto(photoId, text string) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, nil)
+	return ctx.answerPhoto(photoId, text, nil, true)
 }
+func (ctx *MsgContext) AnswerPhotoMarkdown(photoId, text string) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, nil, false)
+}
+
 func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, kb)
+	return ctx.answerPhoto(photoId, text, kb, true)
+}
+func (ctx *MsgContext) AnswerPhotoKeyboardMarkdown(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, kb, false)
+}
+
+func (ctx *MsgContext) AnswerPhotof(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, true)
+}
+func (ctx *MsgContext) AnswerPhotofMarkdown(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, false)
 }

 func (ctx *MsgContext) delete(messageId int) {
@@ -205,18 +243,24 @@ func (ctx *MsgContext) SendAction(action tgapi.ChatActionType) {
 }

 func (ctx *MsgContext) error(err error) {
-	text := fmt.Sprintf(ctx.errorTemplate, utils.EscapeMarkdown(err.Error()))
+	text := fmt.Sprintf(ctx.errorTemplate, err.Error())

 	if ctx.CallbackQueryId != "" {
 		ctx.answerCallbackQuery("", text, false)
 	} else {
-		ctx.answer(text, nil)
+		ctx.answer(text, nil, true)
 	}
 	ctx.botLogger.Errorln(err)
 }
 func (ctx *MsgContext) Error(err error) { ctx.error(err) }

 func (ctx *MsgContext) NewDraft() *Draft {
+	c := context.Background()
+	if err := ctx.Api.Limiter.Wait(c, ctx.Msg.Chat.ID); err != nil {
+		ctx.botLogger.Errorln(err)
+		return nil
+	}
+
 	draft := ctx.draftProvider.NewDraft()
 	draft.chatID = ctx.Msg.Chat.ID
 	draft.messageThreadID = ctx.Msg.MessageThreadID
--- a/plugins.go
+++ b/plugins.go
@@ -15,7 +15,7 @@ const (
 )

 var (
-	CommandRegexInt    = regexp.MustCompile("\\d+")
+	CommandRegexInt    = regexp.MustCompile(`\d+`)
 	CommandRegexString = regexp.MustCompile(".+")
 )

--- a/runners.go
+++ b/runners.go
@@ -13,6 +13,9 @@ type Runner[T DbContext] struct {
 	fn      RunnerFn[T]
 }

+// NewRunner creates a new Runner with async=true by default.
+// Builder methods (Onetime, Async, Timeout) modify the Runner in-place.
+// DO NOT call builder methods concurrently or after Execute().
 func NewRunner[T DbContext](name string, fn RunnerFn[T]) *Runner[T] {
 	return &Runner[T]{
 		name: name, fn: fn, async: true,
--- a/tgapi/api.go
+++ b/tgapi/api.go
@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -12,49 +11,73 @@ import (

 	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
-	"golang.org/x/time/rate"
 )

+// APIOpts holds configuration options for initializing the Telegram API client.
+// Use the provided setter methods to build options — do not construct directly.
 type APIOpts struct {
 	token         string
 	client        *http.Client
 	useTestServer bool
 	apiUrl        string

-	limiter           *rate.Limiter
+	limiter           *utils.RateLimiter
 	dropOverflowLimit bool
 }

-var ErrPoolUnexpected = errors.New("unexpected response from pool")
-
+// NewAPIOpts creates a new APIOpts with default values.
+// Use setter methods to customize behavior.
 func NewAPIOpts(token string) *APIOpts {
-	return &APIOpts{token: token, client: nil, useTestServer: false, apiUrl: "https://api.telegram.org"}
+	return &APIOpts{
+		token:         token,
+		client:        nil,
+		useTestServer: false,
+		apiUrl:        "https://api.telegram.org",
 	}
+}
+
+// SetHTTPClient sets a custom HTTP client. Use this for timeouts, proxies, or custom transport.
+// If not set, a default client with 45s timeout is used.
 func (opts *APIOpts) SetHTTPClient(client *http.Client) *APIOpts {
 	if client != nil {
 		opts.client = client
 	}
 	return opts
 }
+
+// UseTestServer enables use of Telegram's test server (https://api.test.telegram.org).
+// Only for development/testing.
 func (opts *APIOpts) UseTestServer(use bool) *APIOpts {
 	opts.useTestServer = use
 	return opts
 }
+
+// SetAPIUrl overrides the default Telegram API URL.
+// Useful for self-hosted bots or proxies.
 func (opts *APIOpts) SetAPIUrl(apiUrl string) *APIOpts {
 	if apiUrl != "" {
 		opts.apiUrl = apiUrl
 	}
 	return opts
 }
-func (opts *APIOpts) SetLimiter(limiter *rate.Limiter) *APIOpts {
+
+// SetLimiter sets a rate limiter to enforce Telegram's API limits.
+// Recommended: use utils.NewRateLimiter() for correct per-chat and global throttling.
+func (opts *APIOpts) SetLimiter(limiter *utils.RateLimiter) *APIOpts {
 	opts.limiter = limiter
 	return opts
 }
+
+// SetLimiterDrop enables "drop mode" for rate limiting.
+// If true, requests exceeding limits return ErrDropOverflow immediately.
+// If false, requests block until capacity is available.
 func (opts *APIOpts) SetLimiterDrop(b bool) *APIOpts {
 	opts.dropOverflowLimit = b
 	return opts
 }

+// API is the main Telegram Bot API client.
+// It manages HTTP requests, rate limiting, retries, and connection pooling.
 type API struct {
 	token         string
 	client        *http.Client
@@ -62,63 +85,116 @@ type API struct {
 	useTestServer bool
 	apiUrl        string

-	pool              *WorkerPool
-	limiter           *rate.Limiter
+	pool              *workerPool
+	Limiter           *utils.RateLimiter
 	dropOverflowLimit bool
 }

+// NewAPI creates a new API client from options.
+// Always call CloseApi() when done to release resources.
 func NewAPI(opts *APIOpts) *API {
 	l := slog.CreateLogger().Level(utils.GetLoggerLevel()).Prefix("API")
 	l.AddWriter(l.CreateJsonStdoutWriter())
+
 	client := opts.client
 	if client == nil {
 		client = &http.Client{Timeout: time.Second * 45}
 	}
-	pool := NewWorkerPool(16, 256)
-	pool.Start(context.Background())
+
+	pool := newWorkerPool(16, 256)
+	pool.start(context.Background())
+
 	return &API{
-		opts.token, client, l,
-		opts.useTestServer, opts.apiUrl,
-		pool, opts.limiter, opts.dropOverflowLimit,
+		token:             opts.token,
+		client:            client,
+		logger:            l,
+		useTestServer:     opts.useTestServer,
+		apiUrl:            opts.apiUrl,
+		pool:              pool,
+		Limiter:           opts.limiter,
+		dropOverflowLimit: opts.dropOverflowLimit,
 	}
 }
+
+// CloseApi shuts down the internal worker pool and closes the logger.
+// Must be called to avoid resource leaks.
 func (api *API) CloseApi() error {
-	api.pool.Stop()
+	api.pool.stop()
 	return api.logger.Close()
 }
-func (api *API) GetLogger() *slog.Logger { return api.logger }

+// GetLogger returns the internal logger for custom logging.
+func (api *API) GetLogger() *slog.Logger {
+	return api.logger
+}
+
+// ResponseParameters contains Telegram API response metadata (e.g., retry_after, migrate_to_chat_id).
+type ResponseParameters struct {
+	MigrateToChatID *int64 `json:"migrate_to_chat_id,omitempty"`
+	RetryAfter      *int   `json:"retry_after,omitempty"`
+}
+
+// ApiResponse is the standard Telegram Bot API response structure.
+// Generic over Result type R.
 type ApiResponse[R any] struct {
 	Ok          bool                `json:"ok"`
 	Description string              `json:"description,omitempty"`
 	Result      R                   `json:"result,omitempty"`
 	ErrorCode   int                 `json:"error_code,omitempty"`
+	Parameters  *ResponseParameters `json:"parameters,omitempty"`
 }
+
+// TelegramRequest is an internal helper struct.
+// DO NOT USE NewRequest or NewRequestWithChatID — they are unsafe and discouraged.
+// Instead, use explicit methods like SendMessage, GetUpdates, etc.
+//
+// Why? Because using generics with arbitrary types P and R leads to:
+//   - No compile-time validation of parameters
+//   - No IDE autocompletion
+//   - Runtime panics on malformed JSON
+//   - Hard-to-debug errors
+//
+// Recommended: Define specific methods for each Telegram method (see below).
 type TelegramRequest[R, P any] struct {
 	method string
 	params P
+	chatId int64
 }

+// NewRequest and NewRequestWithChatID are DEPRECATED.
+// They encourage unsafe, untyped usage and bypass Go's type safety.
+// Instead, define explicit, type-safe methods for each Telegram API endpoint.
+//
+// Example:
+//
+//	func (api *API) SendMessage(ctx context.Context, chatID int64, text string) (Message, error) { ... }
+//
+// This provides:
+//
+//	✅ Compile-time validation
+//	✅ IDE autocompletion
+//	✅ Clear API surface
+//	✅ Better error messages
+//
+// DO NOT use these constructors in production code.
+// This can be used ONLY for testing or if you NEED method, that wasn't added as function.
 func NewRequest[R, P any](method string, params P) TelegramRequest[R, P] {
-	return TelegramRequest[R, P]{method: method, params: params}
+	return TelegramRequest[R, P]{method, params, 0}
 }
+
+func NewRequestWithChatID[R, P any](method string, params P, chatId int64) TelegramRequest[R, P] {
+	return TelegramRequest[R, P]{method, params, chatId}
+}
+
+// doRequest performs a single HTTP request to Telegram API.
+// Handles rate limiting, retries on 429, and parses responses.
+// Must be called within a worker pool context if using DoWithContext.
 func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, error) {
 	var zero R
-	if api.limiter != nil {
-		if api.dropOverflowLimit {
-			if !api.limiter.Allow() {
-				return zero, errors.New("rate limited")
-			}
-		} else {
-			if err := api.limiter.Wait(ctx); err != nil {
-				return zero, err
-			}
-		}
-	}

 	data, err := json.Marshal(r.params)
 	if err != nil {
-		return zero, err
+		return zero, fmt.Errorf("failed to marshal request: %w", err)
 	}
 	buf := bytes.NewBuffer(data)

@@ -127,36 +203,82 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 		methodPrefix = "/test"
 	}
 	url := fmt.Sprintf("%s/bot%s%s/%s", api.apiUrl, api.token, methodPrefix, r.method)
+
 	req, err := http.NewRequestWithContext(ctx, "POST", url, buf)
 	if err != nil {
-		return zero, err
+		return zero, fmt.Errorf("failed to create request: %w", err)
 	}
+
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+	req.Header.Set("Accept-Encoding", "gzip")
+	req.ContentLength = int64(len(data))

-	api.logger.Debugln("REQ", api.apiUrl, r.method, buf.String())
-	res, err := api.client.Do(req)
-	if err != nil {
+	for {
+		// Apply rate limiting before making the request
+		if api.Limiter != nil {
+			if err := api.Limiter.Check(ctx, api.dropOverflowLimit, r.chatId); err != nil {
 				return zero, err
 			}
-	defer func(Body io.ReadCloser) {
-		_ = Body.Close()
-	}(res.Body)
-
-	data, err = readBody(res.Body)
-	if err != nil {
-		return zero, err
 		}
+
+		api.logger.Debugln("REQ", url, string(data))
+
+		resp, err := api.client.Do(req)
+		if err != nil {
+			return zero, fmt.Errorf("HTTP request failed: %w", err)
+		}
+
+		data, err = readBody(resp.Body)
+		_ = resp.Body.Close() // ensure body is closed
+		if err != nil {
+			return zero, fmt.Errorf("failed to read response body: %w", err)
+		}
+
 		api.logger.Debugln("RES", r.method, string(data))
-	if res.StatusCode != http.StatusOK {
-		return zero, fmt.Errorf("unexpected status code: %d, %s", res.StatusCode, string(data))
+
+		response, err := parseBody[R](data)
+		if err != nil {
+			return zero, fmt.Errorf("failed to parse response: %w", err)
 		}
-	return parseBody[R](data)
+
+		if !response.Ok {
+			// Handle rate limiting (429)
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				api.logger.Warnf("Rate limited by Telegram, retry after %d seconds (chat: %d)", after, r.chatId)
+
+				// Apply cooldown to global or chat-specific limiter
+				if r.chatId > 0 {
+					api.Limiter.SetChatLock(r.chatId, after)
+				} else {
+					api.Limiter.SetGlobalLock(after)
 				}
+
+				// Wait and retry
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // retry request
+				}
+			}
+
+			// Other API errors
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+
+		return response.Result, nil
+	}
+}
+
+// DoWithContext executes the request asynchronously via the worker pool.
+// Returns result or error via channel. Respects context cancellation.
 func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R, error) {
 	var zero R
-	result, err := api.pool.Submit(ctx, func(ctx context.Context) (any, error) {
+
+	resultChan, err := api.pool.submit(ctx, func(ctx context.Context) (any, error) {
 		return r.doRequest(ctx, api)
 	})
 	if err != nil {
@@ -166,33 +288,45 @@ func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R,
 	select {
 	case <-ctx.Done():
 		return zero, ctx.Err()
-	case res := <-result:
-		if res.Err != nil {
-			return zero, res.Err
+	case res := <-resultChan:
+		if res.err != nil {
+			return zero, res.err
 		}
-		if val, ok := res.Value.(R); ok {
+		if val, ok := res.value.(R); ok {
 			return val, nil
 		}
 		return zero, ErrPoolUnexpected
 	}
 }
+
+// Do executes the request synchronously with a background context.
+// Use only for simple, non-critical calls.
 func (r TelegramRequest[R, P]) Do(api *API) (R, error) {
 	return r.DoWithContext(context.Background(), api)
 }

+// readBody reads and limits response body to prevent memory exhaustion.
+// Telegram responses are typically small (<1MB), but we cap at 10MB.
 func readBody(body io.ReadCloser) ([]byte, error) {
-	reader := io.LimitReader(body, 10<<20)
+	reader := io.LimitReader(body, 10<<20) // 10 MB
 	return io.ReadAll(reader)
 }
-func parseBody[R any](data []byte) (R, error) {
-	var zero R
+
+// parseBody unmarshals Telegram API response and returns structured result.
+// Returns ErrRateLimit internally if error_code == 429 — caller must handle via response.Ok check.
+func parseBody[R any](data []byte) (ApiResponse[R], error) {
 	var resp ApiResponse[R]
 	err := json.Unmarshal(data, &resp)
 	if err != nil {
-		return zero, err
+		return resp, fmt.Errorf("failed to unmarshal JSON: %w", err)
 	}
+
 	if !resp.Ok {
-		return zero, fmt.Errorf("[%d] %s", resp.ErrorCode, resp.Description)
+		if resp.ErrorCode == 429 {
+			return resp, ErrRateLimit // internal use only
 		}
-	return resp.Result, nil
+		return resp, fmt.Errorf("[%d] %s", resp.ErrorCode, resp.Description)
+	}
+
+	return resp, nil
 }
--- a/tgapi/attachments_methods.go
+++ b/tgapi/attachments_methods.go
@@ -2,7 +2,7 @@ package tgapi

 type SendPhotoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -24,13 +24,13 @@ type SendPhotoP struct {
 }

 func (api *API) SendPhoto(params SendPhotoP) (Message, error) {
-	req := NewRequest[Message]("sendPhoto", params)
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
 	return req.Do(api)
 }

 type SendAudioP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -53,13 +53,13 @@ type SendAudioP struct {
 }

 func (api *API) SendAudio(params SendAudioP) (Message, error) {
-	req := NewRequest[Message]("sendAudio", params)
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
 	return req.Do(api)
 }

 type SendDocumentP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -79,13 +79,13 @@ type SendDocumentP struct {
 }

 func (api *API) SendDocument(params SendDocumentP) (Message, error) {
-	req := NewRequest[Message]("sendDocument", params)
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
 	return req.Do(api)
 }

 type SendVideoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -114,13 +114,13 @@ type SendVideoP struct {
 }

 func (api *API) SendVideo(params SendVideoP) (Message, error) {
-	req := NewRequest[Message]("sendVideo", params)
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
 	return req.Do(api)
 }

 type SendAnimationP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -145,13 +145,13 @@ type SendAnimationP struct {
 }

 func (api *API) SendAnimation(params SendAnimationP) (Message, error) {
-	req := NewRequest[Message]("sendAnimation", params)
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
 	return req.Do(api)
 }

 type SendVoiceP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -171,13 +171,13 @@ type SendVoiceP struct {
 }

 func (api *API) SendVoice(params *SendVoiceP) (Message, error) {
-	req := NewRequest[Message]("sendVoice", params)
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
 	return req.Do(api)
 }

 type SendVideoNoteP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -195,13 +195,13 @@ type SendVideoNoteP struct {
 }

 func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) {
-	req := NewRequest[Message]("sendVideoNote", params)
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
 	return req.Do(api)
 }

 type SendPaidMediaP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 	StarCount             int    `json:"star_count,omitempty"`
@@ -222,13 +222,13 @@ type SendPaidMediaP struct {
 }

 func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) {
-	req := NewRequest[Message]("sendPaidMedia", params)
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
 	return req.Do(api)
 }

 type SendMediaGroupP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -241,6 +241,6 @@ type SendMediaGroupP struct {
 }

 func (api *API) SendMediaGroup(params SendMediaGroupP) (Message, error) {
-	req := NewRequest[Message]("sendMediaGroup", params)
+	req := NewRequestWithChatID[Message]("sendMediaGroup", params, params.ChatID)
 	return req.Do(api)
 }
--- a/tgapi/chat_methods.go
+++ b/tgapi/chat_methods.go
@@ -1,30 +1,30 @@
 package tgapi

 type BanChatMemberP struct {
-	ChatID         int  `json:"chat_id"`
+	ChatID         int64 `json:"chat_id"`
 	UserID         int   `json:"user_id"`
 	UntilDate      int   `json:"until_date,omitempty"`
 	RevokeMessages bool  `json:"revoke_messages,omitempty"`
 }

 func (api *API) BanChatMember(params BanChatMemberP) (bool, error) {
-	req := NewRequest[bool]("banChatMember", params)
+	req := NewRequestWithChatID[bool]("banChatMember", params, params.ChatID)
 	return req.Do(api)
 }

 type UnbanChatMemberP struct {
-	ChatID       int  `json:"chat_id"`
+	ChatID       int64 `json:"chat_id"`
 	UserID       int   `json:"user_id"`
 	OnlyIfBanned bool  `json:"only_if_banned"`
 }

 func (api *API) UnbanChatMember(params UnbanChatMemberP) (bool, error) {
-	req := NewRequest[bool]("unbanChatMember", params)
+	req := NewRequestWithChatID[bool]("unbanChatMember", params, params.ChatID)
 	return req.Do(api)
 }

 type RestrictChatMemberP struct {
-	ChatID                        int             `json:"chat_id"`
+	ChatID                        int64           `json:"chat_id"`
 	UserID                        int             `json:"user_id"`
 	Permissions                   ChatPermissions `json:"permissions"`
 	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
@@ -32,12 +32,12 @@ type RestrictChatMemberP struct {
 }

 func (api *API) RestrictChatMember(params RestrictChatMemberP) (bool, error) {
-	req := NewRequest[bool]("restrictChatMember", params)
+	req := NewRequestWithChatID[bool]("restrictChatMember", params, params.ChatID)
 	return req.Do(api)
 }

 type PromoteChatMember struct {
-	ChatID      int  `json:"chat_id"`
+	ChatID      int64 `json:"chat_id"`
 	UserID      int   `json:"user_id"`
 	IsAnonymous bool  `json:"is_anonymous,omitempty"`

@@ -60,74 +60,74 @@ type PromoteChatMember struct {
 }

 func (api *API) PromoteChatMember(params PromoteChatMember) (bool, error) {
-	req := NewRequest[bool]("promoteChatMember", params)
+	req := NewRequestWithChatID[bool]("promoteChatMember", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatAdministratorCustomTitleP struct {
-	ChatID      int    `json:"chat_id"`
+	ChatID      int64  `json:"chat_id"`
 	UserID      int    `json:"user_id"`
 	CustomTitle string `json:"custom_title"`
 }

 func (api *API) SetChatAdministratorCustomTitle(params SetChatAdministratorCustomTitleP) (bool, error) {
-	req := NewRequest[bool]("setChatAdministratorCustomTitle", params)
+	req := NewRequestWithChatID[bool]("setChatAdministratorCustomTitle", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatMemberTagP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	UserID int    `json:"user_id"`
 	Tag    string `json:"tag,omitempty"`
 }

 func (api *API) SetChatMemberTag(params SetChatMemberTagP) (bool, error) {
-	req := NewRequest[bool]("setChatMemberTag", params)
+	req := NewRequestWithChatID[bool]("setChatMemberTag", params, params.ChatID)
 	return req.Do(api)
 }

 type BanChatSenderChatP struct {
-	ChatID       int `json:"chat_id"`
-	SenderChatID int `json:"sender_chat_id"`
+	ChatID       int64 `json:"chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
 }

 func (api *API) BanChatSenderChat(params BanChatSenderChatP) (bool, error) {
-	req := NewRequest[bool]("banChatSenderChat", params)
+	req := NewRequestWithChatID[bool]("banChatSenderChat", params, params.ChatID)
 	return req.Do(api)
 }

 type UnbanChatSenderChatP struct {
-	ChatID       int `json:"chat_id"`
-	SenderChatID int `json:"sender_chat_id"`
+	ChatID       int64 `json:"chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
 }

 func (api *API) UnbanChatSenderChat(params BanChatSenderChatP) (bool, error) {
-	req := NewRequest[bool]("unbanChatSenderChat", params)
+	req := NewRequestWithChatID[bool]("unbanChatSenderChat", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatPermissionsP struct {
-	ChatID                        int             `json:"chat_id"`
+	ChatID                        int64           `json:"chat_id"`
 	Permissions                   ChatPermissions `json:"permissions"`
 	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
 }

 func (api *API) SetChatPermissions(params SetChatPermissionsP) (bool, error) {
-	req := NewRequest[bool]("setChatPermissions", params)
+	req := NewRequestWithChatID[bool]("setChatPermissions", params, params.ChatID)
 	return req.Do(api)
 }

 type ExportChatInviteLinkP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) ExportChatInviteLink(params ExportChatInviteLinkP) (string, error) {
-	req := NewRequest[string]("exportChatInviteLink", params)
+	req := NewRequestWithChatID[string]("exportChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type CreateChatInviteLinkP struct {
-	ChatID             int     `json:"chat_id"`
+	ChatID             int64   `json:"chat_id"`
 	Name               *string `json:"name,omitempty"`
 	ExpireDate         int     `json:"expire_date,omitempty"`
 	MemberLimit        int     `json:"member_limit,omitempty"`
@@ -135,12 +135,12 @@ type CreateChatInviteLinkP struct {
 }

 func (api *API) CreateChatInviteLink(params CreateChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("createChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("createChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type EditChatInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`

 	Name               string `json:"name,omitempty"`
@@ -150,206 +150,208 @@ type EditChatInviteLinkP struct {
 }

 func (api *API) EditChatInviteLink(params EditChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("editChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("editChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type CreateChatSubscriptionInviteLinkP struct {
-	ChatID             int    `json:"chat_id"`
+	ChatID             int64  `json:"chat_id"`
 	Name               string `json:"name,omitempty"`
 	SubscriptionPeriod int    `json:"subscription_period,omitempty"`
 	SubscriptionPrice  int    `json:"subscription_price,omitempty"`
 }

 func (api *API) CreateChatSubscriptionInviteLink(params CreateChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("createChatSubscriptionInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("createChatSubscriptionInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type EditChatSubscriptionInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`
 	Name       string `json:"name,omitempty"`
 }

 func (api *API) EditChatSubscriptionInviteLink(params EditChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("editChatSubscriptionInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("editChatSubscriptionInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type RevokeChatInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`
 }

 func (api *API) RevokeChatInviteLink(params RevokeChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("revokeChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("revokeChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }

 type ApproveChatJoinRequestP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 	UserID int   `json:"user_id"`
 }

 func (api *API) ApproveChatJoinRequest(params ApproveChatJoinRequestP) (bool, error) {
-	req := NewRequest[bool]("approveChatJoinRequest", params)
+	req := NewRequestWithChatID[bool]("approveChatJoinRequest", params, params.ChatID)
 	return req.Do(api)
 }

 type DeclineChatJoinRequestP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 	UserID int   `json:"user_id"`
 }

 func (api *API) DeclineChatJoinRequest(params DeclineChatJoinRequestP) (bool, error) {
-	req := NewRequest[bool]("declineChatJoinRequest", params)
+	req := NewRequestWithChatID[bool]("declineChatJoinRequest", params, params.ChatID)
 	return req.Do(api)
 }

 func (api *API) SetChatPhoto() {
 	uploader := NewUploader(api)
-	defer uploader.Close()
+	defer func() {
+		_ = uploader.Close()
+	}()
 }

 type DeleteChatPhotoP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) DeleteChatPhoto(params DeleteChatPhotoP) (bool, error) {
-	req := NewRequest[bool]("deleteChatPhoto", params)
+	req := NewRequestWithChatID[bool]("deleteChatPhoto", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatTitleP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	Title  string `json:"title"`
 }

 func (api *API) SetChatTitle(params SetChatTitleP) (bool, error) {
-	req := NewRequest[bool]("setChatTitle", params)
+	req := NewRequestWithChatID[bool]("setChatTitle", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatDescriptionP struct {
-	ChatID      int    `json:"chat_id"`
+	ChatID      int64  `json:"chat_id"`
 	Description string `json:"description"`
 }

 func (api *API) SetChatDescription(params SetChatDescriptionP) (bool, error) {
-	req := NewRequest[bool]("setChatDescription", params)
+	req := NewRequestWithChatID[bool]("setChatDescription", params, params.ChatID)
 	return req.Do(api)
 }

 type PinChatMessageP struct {
 	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
-	ChatID               int     `json:"chat_id"`
+	ChatID               int64   `json:"chat_id"`
 	MessageID            int     `json:"message_id"`
 	DisableNotification  bool    `json:"disable_notification,omitempty"`
 }

 func (api *API) PinChatMessage(params PinChatMessageP) (bool, error) {
-	req := NewRequest[bool]("pinChatMessage", params)
+	req := NewRequestWithChatID[bool]("pinChatMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type UnpinChatMessageP struct {
 	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
-	ChatID               int     `json:"chat_id"`
+	ChatID               int64   `json:"chat_id"`
 	MessageID            int     `json:"message_id"`
 }

 func (api *API) UnpinChatMessage(params UnpinChatMessageP) (bool, error) {
-	req := NewRequest[bool]("unpinChatMessage", params)
+	req := NewRequestWithChatID[bool]("unpinChatMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type UnpinAllChatMessagesP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) UnpinAllChatMessages(params UnpinAllChatMessagesP) (bool, error) {
-	req := NewRequest[bool]("unpinAllChatMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllChatMessages", params, params.ChatID)
 	return req.Do(api)
 }

 type LeaveChatP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) LeaveChat(params LeaveChatP) (bool, error) {
-	req := NewRequest[bool]("leaveChatP", params)
+	req := NewRequestWithChatID[bool]("leaveChatP", params, params.ChatID)
 	return req.Do(api)
 }

 type GetChatP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) GetChatP(params GetChatP) (ChatFullInfo, error) {
-	req := NewRequest[ChatFullInfo]("getChatP", params)
+	req := NewRequestWithChatID[ChatFullInfo]("getChatP", params, params.ChatID)
 	return req.Do(api)
 }

 type GetChatAdministratorsP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) GetChatAdministrators(params GetChatAdministratorsP) ([]ChatMember, error) {
-	req := NewRequest[[]ChatMember]("getChatAdministrators", params)
+	req := NewRequestWithChatID[[]ChatMember]("getChatAdministrators", params, params.ChatID)
 	return req.Do(api)
 }

 type GetChatMembersCountP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) GetChatMemberCount(params GetChatMembersCountP) (int, error) {
-	req := NewRequest[int]("getChatMemberCount", params)
+	req := NewRequestWithChatID[int]("getChatMemberCount", params, params.ChatID)
 	return req.Do(api)
 }

 type GetChatMemberP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 	UserID int   `json:"user_id"`
 }

 func (api *API) GetChatMember(params GetChatMemberP) (ChatMember, error) {
-	req := NewRequest[ChatMember]("getChatMember", params)
+	req := NewRequestWithChatID[ChatMember]("getChatMember", params, params.ChatID)
 	return req.Do(api)
 }

 type SetChatStickerSetP struct {
-	ChatID         int    `json:"chat_id"`
+	ChatID         int64  `json:"chat_id"`
 	StickerSetName string `json:"sticker_set_name"`
 }

 func (api *API) SetChatStickerSet(params SetChatStickerSetP) (bool, error) {
-	req := NewRequest[bool]("setChatStickerSet", params)
+	req := NewRequestWithChatID[bool]("setChatStickerSet", params, params.ChatID)
 	return req.Do(api)
 }

 type DeleteChatStickerSetP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (api *API) DeleteChatStickerSet(params DeleteChatStickerSetP) (bool, error) {
-	req := NewRequest[bool]("deleteChatStickerSet", params)
+	req := NewRequestWithChatID[bool]("deleteChatStickerSet", params, params.ChatID)
 	return req.Do(api)
 }

 type GetUserChatBoostsP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 	UserID int   `json:"user_id"`
 }

 func (api *API) GetUserChatBoosts(params GetUserChatBoostsP) (UserChatBoosts, error) {
-	req := NewRequest[UserChatBoosts]("getUserChatBoosts", params)
+	req := NewRequestWithChatID[UserChatBoosts]("getUserChatBoosts", params, params.ChatID)
 	return req.Do(api)
 }

 type GetChatGiftsP struct {
-	ChatID                      int    `json:"chat_id"`
+	ChatID                      int64  `json:"chat_id"`
 	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
 	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
 	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
@@ -363,6 +365,6 @@ type GetChatGiftsP struct {
 }

 func (api *API) GetChatGifts(params GetChatGiftsP) (OwnedGifts, error) {
-	req := NewRequest[OwnedGifts]("getChatGifts", params)
+	req := NewRequestWithChatID[OwnedGifts]("getChatGifts", params, params.ChatID)
 	return req.Do(api)
 }
--- a/tgapi/chat_types.go
+++ b/tgapi/chat_types.go
@@ -1,7 +1,7 @@
 package tgapi

 type Chat struct {
-	ID               int     `json:"id"`
+	ID               int64   `json:"id"`
 	Type             string  `json:"type"`
 	Title            *string `json:"title,omitempty"`
 	Username         *string `json:"username,omitempty"`
--- a/tgapi/errors.go
+++ b/tgapi/errors.go
@@ -0,0 +1,7 @@
+package tgapi
+
+import "errors"
+
+var ErrRateLimit = errors.New("rate limit exceeded")
+var ErrPoolUnexpected = errors.New("unexpected response from pool")
+var ErrPoolQueueFull = errors.New("worker pool queue full")
--- a/tgapi/forum_methods.go
+++ b/tgapi/forum_methods.go
@@ -1,24 +1,24 @@
 package tgapi

 type BaseForumTopicP struct {
-	ChatID          int `json:"chat_id"`
+	ChatID          int64 `json:"chat_id"`
 	MessageThreadID int   `json:"message_thread_id"`
 }

-func (api *API) GetForumTopicIconSet() ([]Sticker, error) {
-	req := NewRequest[[]Sticker]("getForumTopicIconSet", NoParams)
+func (api *API) GetForumTopicIconStickers() ([]Sticker, error) {
+	req := NewRequest[[]Sticker]("getForumTopicIconStickers", NoParams)
 	return req.Do(api)
 }

 type CreateForumTopicP struct {
-	ChatID            int                 `json:"chat_id"`
+	ChatID            int64               `json:"chat_id"`
 	Name              string              `json:"name"`
 	IconColor         ForumTopicIconColor `json:"icon_color"`
 	IconCustomEmojiID string              `json:"icon_custom_emoji_id"`
 }

 func (api *API) CreateForumTopic(params CreateForumTopicP) (ForumTopic, error) {
-	req := NewRequest[ForumTopic]("createForumTopic", params)
+	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
 	return req.Do(api)
 }

@@ -29,58 +29,58 @@ type EditForumTopicP struct {
 }

 func (api *API) EditForumTopic(params EditForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editForumTopic", params)
+	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
 	return req.Do(api)
 }

 func (api *API) CloseForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeForumTopic", params)
+	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) ReopenForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenForumTopic", params)
+	req := NewRequestWithChatID[bool]("reopenForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) DeleteForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("deleteForumTopic", params)
+	req := NewRequestWithChatID[bool]("deleteForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnpinAllForumTopicMessages(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllForumTopicMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }

 type BaseGeneralForumTopicP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 type EditGeneralForumTopicP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	Name   string `json:"name"`
 }

 func (api *API) EditGeneralForumTopic(params EditGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }

 func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("hideGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unhideGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllGeneralForumTopicMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }
--- a/tgapi/messages_methods.go
+++ b/tgapi/messages_methods.go
@@ -2,9 +2,9 @@ package tgapi

 type SendMessageP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int64  `json:"direct_messages_topic_id,omitempty"`

 	Text                 string              `json:"text"`
 	ParseMode            ParseMode           `json:"parse_mode,omitempty"`
@@ -21,17 +21,17 @@ type SendMessageP struct {
 }

 func (api *API) SendMessage(params SendMessageP) (Message, error) {
-	req := NewRequest[Message, SendMessageP]("sendMessage", params)
+	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type ForwardMessageP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

 	MessageID           int   `json:"message_id,omitempty"`
-	FromChatID          int  `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
 	VideoStartTimestamp int   `json:"video_start_timestamp,omitempty"`
 	DisableNotification bool  `json:"disable_notification,omitempty"`
 	ProtectContent      bool  `json:"protect_content,omitempty"`
@@ -41,32 +41,32 @@ type ForwardMessageP struct {
 }

 func (api *API) ForwardMessage(params ForwardMessageP) (Message, error) {
-	req := NewRequest[Message]("forwardMessage", params)
+	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type ForwardMessagesP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

-	FromChatID          int   `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
 	MessageIDs          []int `json:"message_ids,omitempty"`
 	DisableNotification bool  `json:"disable_notification,omitempty"`
 	ProtectContent      bool  `json:"protect_content,omitempty"`
 }

 func (api *API) ForwardMessages(params ForwardMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("forwardMessages", params)
+	req := NewRequestWithChatID[[]int]("forwardMessages", params, params.ChatID)
 	return req.Do(api)
 }

 type CopyMessageP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

-	FromChatID          int       `json:"from_chat_id"`
+	FromChatID          int64     `json:"from_chat_id"`
 	MessageID           int       `json:"message_id"`
 	VideoStartTimestamp int       `json:"video_start_timestamp,omitempty"`
 	Caption             string    `json:"caption,omitempty"`
@@ -85,16 +85,16 @@ type CopyMessageP struct {
 }

 func (api *API) CopyMessage(params CopyMessageP) (int, error) {
-	req := NewRequest[int]("copyMessage", params)
+	req := NewRequestWithChatID[int]("copyMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type CopyMessagesP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

-	FromChatID          int   `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
 	MessageIDs          []int `json:"message_ids,omitempty"`
 	DisableNotification bool  `json:"disable_notification,omitempty"`
 	ProtectContent      bool  `json:"protect_content,omitempty"`
@@ -102,13 +102,13 @@ type CopyMessagesP struct {
 }

 func (api *API) CopyMessages(params CopyMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("copyMessages", params)
+	req := NewRequestWithChatID[[]int]("copyMessages", params, params.ChatID)
 	return req.Do(api)
 }

 type SendLocationP struct {
 	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

@@ -130,13 +130,13 @@ type SendLocationP struct {
 }

 func (api *API) SendLocation(params SendLocationP) (Message, error) {
-	req := NewRequest[Message]("sendLocation", params)
+	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
 	return req.Do(api)
 }

 type SendVenueP struct {
 	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

@@ -160,13 +160,13 @@ type SendVenueP struct {
 }

 func (api *API) SendVenue(params SendVenueP) (Message, error) {
-	req := NewRequest[Message]("sendVenue", params)
+	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
 	return req.Do(api)
 }

 type SendContactP struct {
 	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

@@ -186,13 +186,13 @@ type SendContactP struct {
 }

 func (api *API) SendContact(params SendContactP) (Message, error) {
-	req := NewRequest[Message]("sendContact", params)
+	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
 	return req.Do(api)
 }

 type SendPollP struct {
 	BusinessConnectionID int   `json:"business_connection_id,omitempty"`
-	ChatID               int `json:"chat_id"`
+	ChatID               int64 `json:"chat_id"`
 	MessageThreadID      int   `json:"message_thread_id,omitempty"`

 	Question              string            `json:"question"`
@@ -220,13 +220,13 @@ type SendPollP struct {
 }

 func (api *API) SendPoll(params SendPollP) (Message, error) {
-	req := NewRequest[Message]("sendPoll", params)
+	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
 	return req.Do(api)
 }

 type SendChecklistP struct {
 	BusinessConnectionID int            `json:"business_connection_id"`
-	ChatID               int            `json:"chat_id"`
+	ChatID               int64          `json:"chat_id"`
 	Checklist            InputChecklist `json:"checklist"`

 	DisableNotification bool   `json:"disable_notification,omitempty"`
@@ -238,13 +238,13 @@ type SendChecklistP struct {
 }

 func (api *API) SendChecklist(params SendChecklistP) (Message, error) {
-	req := NewRequest[Message]("sendChecklist", params)
+	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
 	return req.Do(api)
 }

 type SendDiceP struct {
 	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
 	MessageThreadID       int   `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`

@@ -261,12 +261,12 @@ type SendDiceP struct {
 }

 func (api *API) SendDice(params SendDiceP) (Message, error) {
-	req := NewRequest[Message]("sendDice", params)
+	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
 	return req.Do(api)
 }

 type SendMessageDraftP struct {
-	ChatID          int             `json:"chat_id"`
+	ChatID          int64           `json:"chat_id"`
 	MessageThreadID int             `json:"message_thread_id,omitempty"`
 	DraftID         uint64          `json:"draft_id"`
 	Text            string          `json:"text"`
@@ -275,31 +275,31 @@ type SendMessageDraftP struct {
 }

 func (api *API) SendMessageDraft(params SendMessageDraftP) (bool, error) {
-	req := NewRequest[bool]("sendMessageDraft", params)
+	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
 	return req.Do(api)
 }

 type SendChatActionP struct {
 	BusinessConnectionID string         `json:"business_connection_id,omitempty"`
-	ChatID               int            `json:"chat_id"`
+	ChatID               int64          `json:"chat_id"`
 	MessageThreadID      int            `json:"message_thread_id,omitempty"`
 	Action               ChatActionType `json:"action"`
 }

 func (api *API) SendChatAction(params SendChatActionP) (bool, error) {
-	req := NewRequest[bool]("sendChatAction", params)
+	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
 	return req.Do(api)
 }

 type SetMessageReactionP struct {
-	ChatId    int            `json:"chat_id"`
+	ChatID    int64          `json:"chat_id"`
 	MessageId int            `json:"message_id"`
 	Reaction  []ReactionType `json:"reaction"`
 	IsBig     bool           `json:"is_big,omitempty"`
 }

 func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {
-	req := NewRequest[bool]("setMessageReaction", params)
+	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
 	return req.Do(api)
 }

@@ -307,7 +307,7 @@ func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {

 type EditMessageTextP struct {
 	BusinessConnectionID string       `json:"business_connection_id,omitempty"`
-	ChatID               int          `json:"chat_id,omitempty"`
+	ChatID               int64        `json:"chat_id,omitempty"`
 	MessageID            int          `json:"message_id,omitempty"`
 	InlineMessageID      string       `json:"inline_message_id,omitempty"`
 	Text                 string       `json:"text"`
@@ -320,18 +320,18 @@ type EditMessageTextP struct {
 func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageText", params)
+		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageText", params)
+	req := NewRequestWithChatID[Message]("editMessageText", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type EditMessageCaptionP struct {
 	BusinessConnectionID string       `json:"business_connection_id,omitempty"`
-	ChatID               int          `json:"chat_id,omitempty"`
+	ChatID               int64        `json:"chat_id,omitempty"`
 	MessageID            int          `json:"message_id,omitempty"`
 	InlineMessageID      string       `json:"inline_message_id,omitempty"`
 	Caption              string       `json:"caption"`
@@ -344,18 +344,18 @@ type EditMessageCaptionP struct {
 func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageCaption", params)
+		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageCaption", params)
+	req := NewRequestWithChatID[Message]("editMessageCaption", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type EditMessageMediaP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	Message              InputMedia            `json:"message"`
@@ -367,18 +367,18 @@ type EditMessageMediaP struct {
 func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageMedia", params)
+		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageMedia", params)
+	req := NewRequestWithChatID[Message]("editMessageMedia", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type EditMessageLiveLocationP struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
-	ChatID               int    `json:"chat_id,omitempty"`
+	ChatID               int64  `json:"chat_id,omitempty"`
 	MessageID            int    `json:"message_id,omitempty"`
 	InlineMessageID      string `json:"inline_message_id,omitempty"`

@@ -396,18 +396,18 @@ type EditMessageLiveLocationP struct {
 func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageLiveLocation", params)
+		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageLiveLocation", params)
+	req := NewRequestWithChatID[Message]("editMessageLiveLocation", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type StopMessageLiveLocationP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
@@ -418,31 +418,31 @@ type StopMessageLiveLocationP struct {
 func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("stopMessageLiveLocation", params)
+		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("stopMessageLiveLocation", params)
+	req := NewRequestWithChatID[Message]("stopMessageLiveLocation", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type EditMessageChecklistP struct {
 	BusinessConnectionID string                `json:"business_connection_id"`
-	ChatID               int                   `json:"chat_id"`
+	ChatID               int64                 `json:"chat_id"`
 	MessageID            int                   `json:"message_id"`
 	Checklist            InputChecklist        `json:"checklist"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
 }

 func (api *API) EditMessageChecklist(params EditMessageChecklistP) (Message, error) {
-	req := NewRequest[Message]("editMessageChecklist", params)
+	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
 	return req.Do(api)
 }

 type EditMessageReplyMarkupP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
@@ -451,66 +451,66 @@ type EditMessageReplyMarkupP struct {
 func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageReplyMarkup", params)
+		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageReplyMarkup", params)
+	req := NewRequestWithChatID[Message]("editMessageReplyMarkup", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }

 type StopPollP struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
-	ChatID               int    `json:"chat_id"`
+	ChatID               int64  `json:"chat_id"`
 	MessageID            int    `json:"message_id"`
 	InlineMessageID      string `json:"inline_message_id,omitempty"`
 }

 func (api *API) StopPoll(params StopPollP) (Poll, error) {
-	req := NewRequest[Poll]("stopPoll", params)
+	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
 	return req.Do(api)
 }

 type ApproveSuggestedPostP struct {
-	ChatID    int `json:"chat_id"`
+	ChatID    int64 `json:"chat_id"`
 	MessageID int   `json:"message_id"`
 	SendDate  int   `json:"send_date,omitempty"`
 }

 func (api *API) ApproveSuggestedPost(params ApproveSuggestedPostP) (bool, error) {
-	req := NewRequest[bool]("approveSuggestedPost", params)
+	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }

 type DeclineSuggestedPostP struct {
-	ChatID    int    `json:"chat_id"`
+	ChatID    int64  `json:"chat_id"`
 	MessageID int    `json:"message_id"`
 	Comment   string `json:"comment,omitempty"`
 }

 func (api *API) DeclineSuggestedPost(params DeclineSuggestedPostP) (bool, error) {
-	req := NewRequest[bool]("declineSuggestedPost", params)
+	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }

 type DeleteMessageP struct {
-	ChatID    int `json:"chat_id"`
+	ChatID    int64 `json:"chat_id"`
 	MessageID int   `json:"message_id"`
 }

 func (api *API) DeleteMessage(params DeleteMessageP) (bool, error) {
-	req := NewRequest[bool]("deleteMessage", params)
+	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
 	return req.Do(api)
 }

 type DeleteMessagesP struct {
-	ChatID     int   `json:"chat_id"`
+	ChatID     int64 `json:"chat_id"`
 	MessageIDs []int `json:"message_ids"`
 }

 func (api *API) DeleteMessages(params DeleteMessagesP) (bool, error) {
-	req := NewRequest[bool]("deleteMessages", params)
+	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
 	return req.Do(api)
 }

--- a/tgapi/messages_types.go
+++ b/tgapi/messages_types.go
@@ -6,9 +6,15 @@ type MessageReplyMarkup struct {
 	InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
 }

+type DirectMessageTopic struct {
+	TopicID int64 `json:"topic_id"`
+	User    *User `json:"user,omitempty"`
+}
+
 type Message struct {
 	MessageID            int                 `json:"message_id"`
 	MessageThreadID      int                 `json:"message_thread_id,omitempty"`
+	DirectMessageTopic   *DirectMessageTopic `json:"direct_message_topic,omitempty"`
 	BusinessConnectionId string              `json:"business_connection_id,omitempty"`
 	From                 *User               `json:"from,omitempty"`

--- a/tgapi/methods.go
+++ b/tgapi/methods.go
@@ -57,6 +57,8 @@ func (api *API) GetFileByLink(link string) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer res.Body.Close()
+	defer func() {
+		_ = res.Body.Close()
+	}()
 	return io.ReadAll(res.Body)
 }
--- a/tgapi/pool.go
+++ b/tgapi/pool.go
@@ -2,91 +2,141 @@ package tgapi

 import (
 	"context"
-	"errors"
 	"sync"
 )

-var ErrPoolQueueFull = errors.New("worker pool queue full")
-
-type RequestEnvelope struct {
-	DoFunc   func(context.Context) (any, error) // функция, которая выполнит запрос и вернет any
-	ResultCh chan RequestResult                 // канал для результата
-}
-type RequestResult struct {
-	Value any
-	Err   error
+// workerPool — приватная структура, управляющая пулом воркеров.
+// Внешний код не может создавать или напрямую взаимодействовать с этой структурой.
+// Используется только через экспортируемые методы newWorkerPool, start, stop, submit.
+type workerPool struct {
+	taskCh    chan requestEnvelope // канал для принятия задач (буферизованный)
+	queueSize int                  // максимальный размер очереди
+	workers   int                  // количество воркеров (горутин)
+	wg        sync.WaitGroup       // синхронизирует завершение всех воркеров при остановке
+	quit      chan struct{}        // канал для сигнала остановки
+	started   bool                 // флаг, указывающий, запущен ли пул
+	startedMu sync.Mutex           // мьютекс для безопасного доступа к started
 }

-// WorkerPool управляет воркерами и очередью
-type WorkerPool struct {
-	taskCh    chan RequestEnvelope
-	queueSize int
-	workers   int
-	wg        sync.WaitGroup
-	quit      chan struct{}
-	started   bool
-	startedMu sync.Mutex
+// requestEnvelope — приватная структура, инкапсулирующая задачу и канал для результата.
+// Используется только внутри пакета для передачи задач воркерам.
+type requestEnvelope struct {
+	doFunc   func(context.Context) (any, error) // функция, выполняющая запрос
+	resultCh chan requestResult                 // канал, через который воркер вернёт результат
 }

-func NewWorkerPool(workers int, queueSize int) *WorkerPool {
-	return &WorkerPool{
-		taskCh:    make(chan RequestEnvelope, queueSize),
+// requestResult — приватная структура, представляющая результат выполнения задачи.
+// Внешний код получает его через канал, но не знает структуры — только через <-chan requestResult.
+type requestResult struct {
+	value any   // значение, возвращённое задачей
+	err   error // ошибка, если возникла
+}
+
+// newWorkerPool создаёт новый пул воркеров с заданным количеством горутин и размером очереди.
+// Это единственный способ создать workerPool — внешний код не может создать его напрямую.
+func newWorkerPool(workers int, queueSize int) *workerPool {
+	if workers <= 0 {
+		workers = 1 // защита от некорректных значений
+	}
+	if queueSize <= 0 {
+		queueSize = 100 // разумный дефолт
+	}
+
+	return &workerPool{
+		taskCh:    make(chan requestEnvelope, queueSize),
 		queueSize: queueSize,
 		workers:   workers,
 		quit:      make(chan struct{}),
 	}
 }

-// Start запускает воркеров
-func (p *WorkerPool) Start(ctx context.Context) {
+// start запускает воркеры (горутины), которые будут обрабатывать задачи из очереди.
+// Метод идемпотентен: если пул уже запущен — ничего не делает.
+// Должен вызываться перед первым вызовом submit.
+func (p *workerPool) start(ctx context.Context) {
 	p.startedMu.Lock()
 	defer p.startedMu.Unlock()
 	if p.started {
-		return
+		return // уже запущен — ничего не делаем
 	}
 	p.started = true
+
+	// Запускаем воркеры — каждый будет обрабатывать задачи в бесконечном цикле
 	for i := 0; i < p.workers; i++ {
 		p.wg.Add(1)
-		go p.worker(ctx)
+		go p.worker(ctx) // запускаем горутину с контекстом
 	}
 }

-// Stop останавливает пул (ждет завершения текущих задач)
-func (p *WorkerPool) Stop() {
-	close(p.quit)
-	p.wg.Wait()
+// stop останавливает пул воркеров.
+// Отправляет сигнал остановки через quit-канал и ждёт завершения всех активных задач.
+// Безопасно вызывать многократно — после остановки повторные вызовы не имеют эффекта.
+func (p *workerPool) stop() {
+	close(p.quit) // сигнал для всех воркеров — выйти из цикла
+	p.wg.Wait()   // ждём, пока все воркеры завершатся
 }

-// Submit отправляет задачу в очередь и возвращает канал для результата
-func (p *WorkerPool) Submit(ctx context.Context, do func(context.Context) (any, error)) (<-chan RequestResult, error) {
+// submit отправляет задачу в очередь и возвращает канал, через который будет получен результат.
+// Если очередь переполнена — возвращает ErrPoolQueueFull.
+// Канал результата имеет буфер 1, чтобы не блокировать воркера при записи.
+// Контекст используется для отмены задачи, если клиент отменил запрос до отправки.
+func (p *workerPool) submit(ctx context.Context, do func(context.Context) (any, error)) (<-chan requestResult, error) {
+	// Проверяем, не превышена ли очередь
 	if len(p.taskCh) >= p.queueSize {
 		return nil, ErrPoolQueueFull
 	}

-	resultCh := make(chan RequestResult, 1) // буфер 1, чтобы не блокировать воркера
-	envelope := RequestEnvelope{do, resultCh}
+	// Создаём канал для результата — буферизованный, чтобы не блокировать воркера
+	resultCh := make(chan requestResult, 1)
+
+	// Создаём обёртку задачи
+	envelope := requestEnvelope{
+		doFunc:   do,
+		resultCh: resultCh,
+	}
+
+	// Пытаемся отправить задачу в очередь
 	select {
 	case <-ctx.Done():
+		// Клиент отменил операцию до отправки — возвращаем ошибку отмены
 		return nil, ctx.Err()
 	case p.taskCh <- envelope:
+		// Успешно отправлено — возвращаем канал для чтения результата
 		return resultCh, nil
 	default:
+		// Очередь переполнена — не должно происходить при проверке len(p.taskCh), но на всякий случай
 		return nil, ErrPoolQueueFull
 	}
 }

-// worker выполняет задачи
-func (p *WorkerPool) worker(ctx context.Context) {
-	defer p.wg.Done()
+// worker — приватная горутина, выполняющая задачи из очереди.
+// Каждый воркер работает в бесконечном цикле, пока не получит сигнал остановки.
+// При получении задачи:
+//   - вызывает doFunc с контекстом
+//   - записывает результат в resultCh
+//   - закрывает канал, чтобы клиент мог прочитать и завершить
+//
+// После закрытия quit-канала — воркер завершает работу.
+func (p *workerPool) worker(ctx context.Context) {
+	defer p.wg.Done() // уменьшаем WaitGroup при завершении горутины
+
 	for {
 		select {
 		case <-p.quit:
+			// Получен сигнал остановки — выходим из цикла
 			return
+
 		case envelope := <-p.taskCh:
-			// Выполняем задачу с переданным контекстом (или можно использовать свой)
-			val, err := envelope.DoFunc(ctx)
-			envelope.ResultCh <- RequestResult{Value: val, Err: err}
-			close(envelope.ResultCh)
+			// Выполняем задачу с переданным контекстом (клиентский или общий)
+			value, err := envelope.doFunc(ctx)
+
+			// Записываем результат в канал — не блокируем, т.к. буфер 1
+			envelope.resultCh <- requestResult{
+				value: value,
+				err:   err,
+			}
+			// Закрываем канал — клиент знает, что результат пришёл и больше не будет
+			close(envelope.resultCh)
 		}
 	}
 }
--- a/tgapi/stickers_methods.go
+++ b/tgapi/stickers_methods.go
@@ -2,7 +2,7 @@ package tgapi

 type SendStickerP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -15,7 +15,7 @@ type SendStickerP struct {
 }

 func (api *API) SendSticker(params SendStickerP) (Message, error) {
-	req := NewRequest[Message]("sendSticker", params)
+	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
 	return req.Do(api)
 }

--- a/tgapi/types.go
+++ b/tgapi/types.go
@@ -261,20 +261,20 @@ type Gifts struct {
 	Gifts []Gift `json:"gifts"`
 }

+type OwnedGiftType string
+
 const (
 	OwnedGiftRegularType OwnedGiftType = "regular"
 	OwnedGiftUniqueType  OwnedGiftType = "unique"
 )

-type OwnedGiftType string
-type BaseOwnedGift struct {
+type OwnedGift struct {
 	Type        OwnedGiftType `json:"type"`
 	OwnerGiftID *string       `json:"owner_gift_id,omitempty"`
 	SendDate    *int          `json:"send_date,omitempty"`
 	IsSaved     *bool         `json:"is_saved,omitempty"`
-}
-type OwnedGiftRegular struct {
-	BaseOwnedGift
+
+	// Поля, характерные для "regular"
 	Gift                    Gift            `json:"gift"`
 	SenderUser              User            `json:"sender_user,omitempty"`
 	Text                    string          `json:"text,omitempty"`
@@ -286,18 +286,15 @@ type OwnedGiftRegular struct {
 	PrepaidUpgradeStarCount *int            `json:"prepaid_upgrade_star_count,omitempty"`
 	IsUpgradeSeparate       *bool           `json:"is_upgrade_separate,omitempty"`
 	UniqueGiftNumber        *int            `json:"unique_gift_number,omitempty"`
-}
-type OwnedGiftUnique struct {
-	BaseOwnedGift
+
+	// Поля, характерные для "unique"
 	CanBeTransferred  *bool `json:"can_be_transferred,omitempty"`
 	TransferStarCount *int  `json:"transfer_star_count,omitempty"`
 	NextTransferDate  *int  `json:"next_transfer_date,omitempty"`
 }
+
 type OwnedGifts struct {
 	TotalCount int         `json:"total_count"`
-	Gifts      []struct {
-		OwnedGiftRegular
-		OwnedGiftUnique
-	} `json:"gifts"`
+	Gifts      []OwnedGift `json:"gifts"`
 	NextOffset string      `json:"next_offset"`
 }
--- a/tgapi/uploader_api.go
+++ b/tgapi/uploader_api.go
@@ -8,6 +8,7 @@ import (
 	"mime/multipart"
 	"net/http"
 	"path/filepath"
+	"time"

 	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
@@ -59,24 +60,17 @@ type UploaderRequest[R, P any] struct {
 	method string
 	files  []UploaderFile
 	params P
+	chatId int64
 }

 func NewUploaderRequest[R, P any](method string, params P, files ...UploaderFile) UploaderRequest[R, P] {
-	return UploaderRequest[R, P]{method, files, params}
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: 0}
+}
+func NewUploaderRequestWithChatID[R, P any](method string, params P, chatId int64, files ...UploaderFile) UploaderRequest[R, P] {
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: chatId}
 }
 func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R, error) {
 	var zero R
-	if up.api.limiter != nil {
-		if up.api.dropOverflowLimit {
-			if !up.api.limiter.Allow() {
-				return zero, errors.New("rate limited")
-			}
-		} else {
-			if err := up.api.limiter.Wait(ctx); err != nil {
-				return zero, err
-			}
-		}
-	}

 	buf, contentType, err := prepareMultipart(r.files, r.params)
 	if err != nil {
@@ -95,26 +89,66 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 	req.Header.Set("Content-Type", contentType)
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+	req.Header.Set("Accept-Encoding", "gzip")
+	req.ContentLength = int64(buf.Len())
+
+	for {
+		if up.api.Limiter != nil {
+			if up.api.dropOverflowLimit {
+				if !up.api.Limiter.GlobalAllow() {
+					return zero, errors.New("rate limited")
+				}
+			} else {
+				if err := up.api.Limiter.GlobalWait(ctx); err != nil {
+					return zero, err
+				}
+			}
+		}

 		up.logger.Debugln("UPLOADER REQ", r.method)
-	res, err := up.api.client.Do(req)
+		resp, err := up.api.client.Do(req)
 		if err != nil {
 			return zero, err
 		}
-	defer res.Body.Close()

-	body, err := readBody(res.Body)
+		body, err := readBody(resp.Body)
+		_ = resp.Body.Close()
+		if err != nil {
+			return zero, err
+		}
 		up.logger.Debugln("UPLOADER RES", r.method, string(body))
-	if res.StatusCode != http.StatusOK {
-		return zero, fmt.Errorf("unexpected status code: %d, %s", res.StatusCode, string(body))
+
+		response, err := parseBody[R](body)
+		if err != nil {
+			return zero, err
 		}

-	return parseBody[R](body)
+		if !response.Ok {
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				up.logger.Warnf("Rate limited, retry after %d seconds (chat: %d)", after, r.chatId)
+				if r.chatId > 0 {
+					up.api.Limiter.SetChatLock(r.chatId, after)
+				} else {
+					up.api.Limiter.SetGlobalLock(after)
+				}
+
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // Повторяем запрос
+				}
+			}
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+		return response.Result, nil
+	}
 }
 func (r UploaderRequest[R, P]) DoWithContext(ctx context.Context, up *Uploader) (R, error) {
 	var zero R

-	result, err := up.api.pool.Submit(ctx, func(ctx context.Context) (any, error) {
+	result, err := up.api.pool.submit(ctx, func(ctx context.Context) (any, error) {
 		return r.doRequest(ctx, up)
 	})
 	if err != nil {
@@ -125,10 +159,10 @@ func (r UploaderRequest[R, P]) DoWithContext(ctx context.Context, up *Uploader)
 	case <-ctx.Done():
 		return zero, ctx.Err()
 	case res := <-result:
-		if res.Err != nil {
-			return zero, res.Err
+		if res.err != nil {
+			return zero, res.err
 		}
-		if val, ok := res.Value.(R); ok {
+		if val, ok := res.value.(R); ok {
 			return val, nil
 		}
 		return zero, ErrPoolUnexpected
@@ -145,24 +179,29 @@ func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, str
 	for _, file := range files {
 		fw, err := w.CreateFormFile(string(file.field), file.filename)
 		if err != nil {
-			_ = w.Close()
-			return buf, w.FormDataContentType(), err
+			_ = w.Close() // Закрываем, чтобы не было утечки
+			return nil, "", err
 		}

 		_, err = fw.Write(file.data)
 		if err != nil {
 			_ = w.Close()
-			return buf, w.FormDataContentType(), err
+			return nil, "", err
 		}
 	}

-	err := utils.Encode(w, params)
+	err := utils.Encode(w, params) // Предполагается, что это записывает в w
 	if err != nil {
 		_ = w.Close()
-		return buf, w.FormDataContentType(), err
+		return nil, "", err
 	}
-	err = w.Close()
-	return buf, w.FormDataContentType(), err
+
+	err = w.Close() // ✅ ОБЯЗАТЕЛЬНО вызвать в конце — иначе запрос битый!
+	if err != nil {
+		return nil, "", err
+	}
+
+	return buf, w.FormDataContentType(), nil
 }

 func uploaderTypeByExt(filename string) UploaderFileType {
--- a/tgapi/uploader_methods.go
+++ b/tgapi/uploader_methods.go
@@ -2,7 +2,7 @@ package tgapi

 type UploadPhotoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -23,13 +23,13 @@ type UploadPhotoP struct {
 }

 func (u *Uploader) UploadPhoto(params UploadPhotoP, file UploaderFile) (Message, error) {
-	req := NewUploaderRequest[Message]("sendPhoto", params, file)
+	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
 	return req.Do(u)
 }

 type UploadAudioP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -52,13 +52,13 @@ type UploadAudioP struct {
 }

 func (u *Uploader) UploadAudio(params UploadAudioP, files ...UploaderFile) (Message, error) {
-	req := NewUploaderRequest[Message]("sendAudio", params, files...)
+	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
 	return req.Do(u)
 }

 type UploadDocumentP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -84,7 +84,7 @@ func (u *Uploader) UploadDocument(params UploadDocumentP, files ...UploaderFile)

 type UploadVideoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -117,7 +117,7 @@ func (u *Uploader) UploadVideo(params UploadVideoP, files ...UploaderFile) (Mess

 type UploadAnimationP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -148,7 +148,7 @@ func (u *Uploader) UploadAnimation(params UploadAnimationP, files ...UploaderFil

 type UploadVoiceP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -174,7 +174,7 @@ func (u *Uploader) UploadVoice(params UploadVoiceP, files ...UploaderFile) (Mess

 type UploadVideoNoteP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`

@@ -197,7 +197,7 @@ func (u *Uploader) UploadVideoNote(params UploadVideoNoteP, files ...UploaderFil
 }

 type UploadChatPhotoP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }

 func (u *Uploader) UploadChatPhoto(params UploadChatPhotoP, photo UploaderFile) (Message, error) {
--- a/utils/limiter.go
+++ b/utils/limiter.go
@@ -0,0 +1,204 @@
+package utils
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+var ErrDropOverflow = errors.New("drop overflow limit")
+
+// RateLimiter implements per-chat and global rate limiting with optional blocking.
+// It supports two modes:
+//   - "drop" mode: immediately reject if limits are exceeded.
+//   - "wait" mode: block until capacity is available.
+type RateLimiter struct {
+	globalLockUntil time.Time     // global cooldown timestamp (set by API errors)
+	globalLimiter   *rate.Limiter // global token bucket (30 req/sec)
+	globalMu        sync.RWMutex  // protects globalLockUntil and globalLimiter
+
+	chatLocks    map[int64]time.Time     // per-chat cooldown timestamps
+	chatLimiters map[int64]*rate.Limiter // per-chat token buckets (1 req/sec)
+	chatMu       sync.Mutex              // protects chatLocks and chatLimiters
+}
+
+// NewRateLimiter creates a new RateLimiter with default limits.
+// Global: 30 requests per second, burst 30.
+// Per-chat: 1 request per second, burst 1.
+func NewRateLimiter() *RateLimiter {
+	return &RateLimiter{
+		globalLimiter: rate.NewLimiter(30, 30),
+		chatLimiters:  make(map[int64]*rate.Limiter),
+		chatLocks:     make(map[int64]time.Time),
+	}
+}
+
+// SetGlobalLock sets a global cooldown period (e.g., after receiving 429 from Telegram).
+// If retryAfter <= 0, no lock is applied.
+func (rl *RateLimiter) SetGlobalLock(retryAfter int) {
+	if retryAfter <= 0 {
+		return
+	}
+	rl.globalMu.Lock()
+	defer rl.globalMu.Unlock()
+	rl.globalLockUntil = time.Now().Add(time.Duration(retryAfter) * time.Second)
+}
+
+// SetChatLock sets a cooldown for a specific chat (e.g., after 429 for that chat).
+// If retryAfter <= 0, no lock is applied.
+func (rl *RateLimiter) SetChatLock(chatID int64, retryAfter int) {
+	if retryAfter <= 0 {
+		return
+	}
+	rl.chatMu.Lock()
+	defer rl.chatMu.Unlock()
+	rl.chatLocks[chatID] = time.Now().Add(time.Duration(retryAfter) * time.Second)
+}
+
+// GlobalWait blocks until a global request can be made.
+// Waits for both global cooldown and token bucket availability.
+func (rl *RateLimiter) GlobalWait(ctx context.Context) error {
+	if err := rl.waitForGlobalUnlock(ctx); err != nil {
+		return err
+	}
+	return rl.globalLimiter.Wait(ctx)
+}
+
+// Wait blocks until a request for the given chat can be made.
+// Waits for: chat cooldown → global cooldown → chat token bucket.
+// Note: Global limit is checked *before* chat limit to avoid overloading upstream.
+func (rl *RateLimiter) Wait(ctx context.Context, chatID int64) error {
+	if err := rl.waitForChatUnlock(ctx, chatID); err != nil {
+		return err
+	}
+	if err := rl.waitForGlobalUnlock(ctx); err != nil {
+		return err
+	}
+	limiter := rl.getChatLimiter(chatID)
+	return limiter.Wait(ctx)
+}
+
+// GlobalAllow checks if a global request can be made without blocking.
+// Returns false if either global cooldown is active or token bucket is exhausted.
+func (rl *RateLimiter) GlobalAllow() bool {
+	rl.globalMu.RLock()
+	until := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+
+	if !until.IsZero() && time.Now().Before(until) {
+		return false
+	}
+	return rl.globalLimiter.Allow()
+}
+
+// Allow checks if a request for the given chat can be made without blocking.
+// Returns false if: global cooldown, chat cooldown, global limiter, or chat limiter denies.
+// Note: Global limiter is checked before chat limiter — upstream limits take priority.
+func (rl *RateLimiter) Allow(chatID int64) bool {
+	// Check global cooldown
+	rl.globalMu.RLock()
+	globalUntil := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+	if !globalUntil.IsZero() && time.Now().Before(globalUntil) {
+		return false
+	}
+
+	// Check chat cooldown
+	rl.chatMu.Lock()
+	chatUntil, ok := rl.chatLocks[chatID]
+	rl.chatMu.Unlock()
+	if ok && !chatUntil.IsZero() && time.Now().Before(chatUntil) {
+		return false
+	}
+
+	// Check global token bucket
+	if !rl.globalLimiter.Allow() {
+		return false
+	}
+
+	// Check chat token bucket
+	limiter := rl.getChatLimiter(chatID)
+	return limiter.Allow()
+}
+
+// Check applies rate limiting based on configuration.
+// If dropOverflow is true:
+//   - Immediately returns ErrDropOverflow if either global or chat limit is exceeded.
+//
+// Else:
+//   - If chatID != 0: waits for chat-specific capacity (including global limit).
+//   - If chatID == 0: waits for global capacity only.
+//
+// chatID == 0 means no specific chat context (e.g., inline query, webhook without chat).
+func (rl *RateLimiter) Check(ctx context.Context, dropOverflow bool, chatID int64) error {
+	if dropOverflow {
+		if chatID != 0 && !rl.Allow(chatID) {
+			return ErrDropOverflow
+		}
+		if !rl.GlobalAllow() {
+			return ErrDropOverflow
+		}
+	} else if chatID != 0 {
+		if err := rl.Wait(ctx, chatID); err != nil {
+			return err
+		}
+	} else {
+		if err := rl.GlobalWait(ctx); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// waitForGlobalUnlock blocks until global cooldown expires or context is done.
+// Does not check token bucket — only cooldown.
+func (rl *RateLimiter) waitForGlobalUnlock(ctx context.Context) error {
+	rl.globalMu.RLock()
+	until := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+
+	if until.IsZero() || time.Now().After(until) {
+		return nil
+	}
+
+	select {
+	case <-time.After(time.Until(until)):
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// waitForChatUnlock blocks until the specified chat's cooldown expires or context is done.
+// Does not check token bucket — only cooldown.
+func (rl *RateLimiter) waitForChatUnlock(ctx context.Context, chatID int64) error {
+	rl.chatMu.Lock()
+	until, ok := rl.chatLocks[chatID]
+	rl.chatMu.Unlock()
+
+	if !ok || until.IsZero() || time.Now().After(until) {
+		return nil
+	}
+
+	select {
+	case <-time.After(time.Until(until)):
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// getChatLimiter returns the rate limiter for the given chat, creating it if needed.
+// Uses 1 request per second with burst of 1 — conservative for per-user limits.
+// Must be called with rl.chatMu held.
+func (rl *RateLimiter) getChatLimiter(chatID int64) *rate.Limiter {
+	if lim, ok := rl.chatLimiters[chatID]; ok {
+		return lim
+	}
+	lim := rate.NewLimiter(1, 1)
+	rl.chatLimiters[chatID] = lim
+	return lim
+}
--- a/utils/multipart.go
+++ b/utils/multipart.go
@@ -1,7 +1,6 @@
 package utils

 import (
-	"encoding/json"
 	"fmt"
 	"io"
 	"mime/multipart"
@@ -26,33 +25,31 @@ func Encode[T any](w *multipart.Writer, req T) error {
 		field := v.Field(i)
 		fieldType := t.Field(i)

-		formTags := strings.Split(fieldType.Tag.Get("json"), ",")
-		fieldName := ""
-		if len(formTags) == 0 {
-			formTags = strings.Split(fieldType.Tag.Get("json"), ",")
+		jsonTag := fieldType.Tag.Get("json")
+		if jsonTag == "" {
+			jsonTag = fieldType.Name
 		}

-		if len(formTags) > 0 {
-			fieldName = formTags[0]
+		parts := strings.Split(jsonTag, ",")
+		fieldName := parts[0]
 		if fieldName == "-" {
 			continue
 		}
-			if slices.Index(formTags, "omitempty") >= 0 {
-				if field.IsZero() {
+
+		// Handle omitempty
+		isEmpty := field.IsZero()
+		if slices.Contains(parts, "omitempty") && isEmpty {
 			continue
 		}
-			}
-		} else {
-			fieldName = strings.ToLower(fieldType.Name)
-		}

 		var (
 			fw  io.Writer
 			err error
 		)
+
 		switch field.Kind() {
 		case reflect.String:
-			if field.String() != "" {
+			if !isEmpty {
 				fw, err = w.CreateFormField(fieldName)
 				if err == nil {
 					_, err = fw.Write([]byte(field.String()))
@@ -80,24 +77,23 @@ func Encode[T any](w *multipart.Writer, req T) error {
 			}
 		case reflect.Slice:
 			if field.Type().Elem().Kind() == reflect.Uint8 && !field.IsNil() {
+				// Handle []byte as file upload (e.g., thumbnail)
 				filename := fieldType.Tag.Get("filename")
 				if filename == "" {
 					filename = fieldName
 				}
-
-				ext := ""
-				filename = filename + ext
-
 				fw, err = w.CreateFormFile(fieldName, filename)
 				if err == nil {
 					_, err = fw.Write(field.Bytes())
 				}
 			} else if !field.IsNil() {
-				// Handle slice of primitive values (as multiple form fields with the same name)
+				// Handle []string, []int, etc. — send as multiple fields with same name
 				for j := 0; j < field.Len(); j++ {
 					elem := field.Index(j)
 					fw, err = w.CreateFormField(fieldName)
-					if err == nil {
+					if err != nil {
+						break
+					}
 					switch elem.Kind() {
 					case reflect.String:
 						_, err = fw.Write([]byte(elem.String()))
@@ -105,20 +101,23 @@ func Encode[T any](w *multipart.Writer, req T) error {
 						_, err = fw.Write([]byte(strconv.FormatInt(elem.Int(), 10)))
 					case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
 						_, err = fw.Write([]byte(strconv.FormatUint(elem.Uint(), 10)))
+					case reflect.Bool:
+						_, err = fw.Write([]byte(strconv.FormatBool(elem.Bool())))
+					case reflect.Float32, reflect.Float64:
+						_, err = fw.Write([]byte(strconv.FormatFloat(elem.Float(), 'f', -1, 64)))
 					}
+					if err != nil {
+						break
 					}
 				}
 			}

 		case reflect.Struct:
-			var jsonData []byte
-			jsonData, err = json.Marshal(field.Interface())
-			if err == nil {
-				fw, err = w.CreateFormField(fieldName)
-				if err == nil {
-					_, err = fw.Write(jsonData)
-				}
-			}
+			// Don't serialize structs as JSON — flatten them!
+			// Telegram doesn't support nested JSON in form-data.
+			// If you need nested data, use separate fields (e.g., ParseMode, CaptionEntities)
+			// This is a design choice — you should avoid nested structs in params.
+			return fmt.Errorf("nested structs are not supported in params — use flat fields")
 		}

 		if err != nil {
--- a/utils/utils.go
+++ b/utils/utils.go
@@ -1,7 +1,6 @@
 package utils

 import (
-	"fmt"
 	"os"
 	"strings"

@@ -16,6 +15,7 @@ func GetLoggerLevel() slog.LogLevel {
 	return level
 }

+// EscapeMarkdown Deprecated. Use MarkdownV2
 func EscapeMarkdown(s string) string {
 	s = strings.ReplaceAll(s, "_", `\_`)
 	s = strings.ReplaceAll(s, "*", `\*`)
@@ -23,10 +23,20 @@ func EscapeMarkdown(s string) string {
 	return strings.ReplaceAll(s, "`", "\\`")
 }

+// EscapeHTML escapes special characters for Telegram HTML parse mode.
+func EscapeHTML(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	return s
+}
+
+// EscapeMarkdownV2 escapes special characters for Telegram MarkdownV2.
+// https://core.telegram.org/bots/api#markdownv2-style
 func EscapeMarkdownV2(s string) string {
-	symbols := []string{"_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
+	symbols := []string{"_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!", "\\"}
 	for _, symbol := range symbols {
-		s = strings.ReplaceAll(s, symbol, fmt.Sprintf("\\%s", symbol))
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
 	}
 	return s
 }
--- a/utils/version.go
+++ b/utils/version.go
@@ -1,9 +1,9 @@
 package utils

 const (
-	VersionString = "1.0.0-beta.4"
+	VersionString = "1.0.0-beta.11"
 	VersionMajor  = 1
 	VersionMinor  = 0
 	VersionPatch  = 0
-	Beta          = 4
+	Beta          = 11
 )
Author	SHA1	Message	Date
ScuroNeko	4dc172a3b5	v1.0.0 beta 11	2026-03-06 12:46:30 +03:00
ScuroNeko	f42d47af53	v1.0.0 beta 10	2026-03-06 12:12:16 +03:00
ScuroNeko	9895edf966	v1.0.0 beta 9	2026-03-06 11:59:17 +03:00
ScuroNeko	6cf3355a36	v1.0.0 beta 8; ratelimt war	2026-03-02 17:06:13 +03:00
ScuroNeko	fa7a296a66	v1.0.0 beta 7; ratelimt war	2026-03-02 16:49:00 +03:00
ScuroNeko	7101aba548	v1.0.0 beta 6	2026-03-02 00:08:26 +03:00
ScuroNeko	2de46a27c8	v1.0.0 beta 5	2026-03-01 23:40:27 +03:00