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"
)

func main() {
    bot, err := tgbot.NewBot("<BOT_TOKEN>")
    if err != nil {
        log.Fatal(err)
    }

    _, err = bot.SendMessage(context.Background(), &tgbot.SendMessageParams{
        ChatID: int64(123456789),
        Text:   "hello from tgbot",
    })
    if err != 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"
)

func main() {
    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()
        if msg == nil || msg.Chat == nil {
            return nil
        }
        _, err := c.Bot.SendMessage(ctx, &tgbot.SendMessageParams{
            ChatID: msg.Chat.ID,
            Text:   "welcome",
        })
        return err
    }))

    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