tgbot

English | 简体中文 | Español | 日本語

Web documentation:https://tgbot.bestcheapvps.org

A lightweight, strongly typed Telegram Bot API SDK for Go with zero third-party runtime dependencies.

tgbot is an open-source Go SDK for building Telegram bots with clean abstractions, full Bot API coverage, typed union decoding, webhook support, and production-friendly long polling.

Why tgbot?

• Full Telegram Bot API method and type coverage
• Strongly typed union decoding for polymorphic Telegram fields and results
• Zero third-party runtime dependencies (standard library only)
• File upload helpers for file_id, URL, local path, and io.Reader
• Opt-in retries with bounded backoff, Telegram retry_after, and safe request telemetry
• Async long polling with channel subscriptions and bounded application dispatch
• PTB-style routing groups, middleware, priorities, filters, and propagation control in ext
• Fixed-size dispatcher workers with queue backpressure and explicit shutdown
• Standard-library test helpers in tgutil and tgbottest

Quick Start

package main
import (
"context""log""github.com/cloudapp3/tgbot"
)
funcmain() {
bot, err:=tgbot.NewBot("<BOT_TOKEN>")
iferr!=nil {
log.Fatal(err)
}
_, err=bot.SendMessage(context.Background(), &tgbot.SendMessageParams{
ChatID: int64(123456789),
Text: "hello from tgbot",
})
iferr!=nil {
log.Fatal(err)
}
}

Install

go get github.com/cloudapp3/tgbot

Request Governance

Requests are attempted exactly once by default. Retries are explicit because a lost response from a side-effecting Telegram method can make a retry duplicate the operation.

bot, err:=tgbot.NewBot(
"<BOT_TOKEN>",
tgbot.WithRetryPolicy(tgbot.ExponentialRetryPolicy{
MaxAttempts: 3,
InitialDelay: 200*time.Millisecond,
MaxDelay: 5*time.Second,
Jitter: 0.2,
}),
tgbot.WithRequestObserver(func(event tgbot.RequestEvent) {
log.Printf("method=%s attempt=%d status=%d api_code=%d duration=%s err=%v",
event.Method, event.Attempt, event.StatusCode, event.APIErrorCode, event.Duration, event.Err)
}),
)

Observer and debug logger events exclude the bot token, request URL, parameters, and body. Arbitrary InputFile.Reader uploads are never retried; JSON, file ID, URL, and local-path requests can be rebuilt for another attempt.

Webhook Routing (ext)

package main
import (
"context""net/http""time""github.com/cloudapp3/tgbot""github.com/cloudapp3/tgbot/ext"
)
funcmain() {
bot, _:=tgbot.NewBot("<BOT_TOKEN>")
app, _:=ext.NewApplication(bot)
app.AddHandler(ext.NewCommandHandler("start", func(ctx context.Context, c*ext.Context) error {
msg:=c.EffectiveMessage()
ifmsg==nil||msg.Chat==nil {
returnnil
}
_, err:=c.Bot.SendMessage(ctx, &tgbot.SendMessageParams{
ChatID: msg.Chat.ID,
Text: "welcome",
})
returnerr
}))
mux:=http.NewServeMux()
mux.Handle("/telegram/webhook", app.WebhookHandler("<SECRET_TOKEN>"))
server:=&http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5*time.Second,
ReadTimeout: 15*time.Second,
WriteTimeout: 45*time.Second,
IdleTimeout: 60*time.Second,
}
_=server.ListenAndServe()
}

For bounded concurrent processing or enqueue-first webhook acknowledgement, use an explicitly owned ext.Dispatcher. Queue saturation and closed dispatchers return 503 in AckAfterEnqueue mode. See ext/README.md.

Test Helpers

• tgutil provides small message, upload, button, and keyboard constructors.
• tgbottest.NewServer provides a concurrency-safe fake Telegram API with FIFO responses and isolated JSON/multipart request snapshots.

Examples

• examples/quickstart
• examples/webhook
• examples/commands
• examples/async_updates
• examples/ext_polling

Official Coverage

This SDK is verified against the official Telegram Bot API documentation at https://core.telegram.org/bots/api. As of 2026-07-19, the latest official release on that page is Bot API 10.2, published on July 14, 2026.

The machine-readable api/telegram-bot-api.json pins the source snapshot path, release identity, fetch date, and compressed and decompressed SHA-256 digests.

./scripts/check_generated.sh
go run ./cmd/apicheck

Sync SDK Definitions

go run ./cmd/apigen

If you already downloaded the official HTML page:

go run ./cmd/apigen -html /tmp/telegram_bot_api.html

Key files:

• sdk_types.go
• sdk_methods.go
• sdk_unions.go

Development

go test ./...
go test -race ./...
go vet ./...
python3 -m unittest discover -s scripts -p '*_test.py' -v
./scripts/check_generated.sh
go run ./cmd/apicheck

License

MIT