mirror of
https://github.com/lukaszraczylo/go-telegram.git
synced 2026-06-05 22:43:59 +00:00
lukaszraczylo
9072e9eafb
A fully-generated, strongly-typed Go client for the Telegram Bot API. * 176 methods + 301 types generated from Bot API v10.0 * 1408 auto-generated tests (8 scenarios per method) * Typed unions throughout — no 'any' in the public surface * Pluggable HTTP transport and JSON codec (default goccy/go-json) * Built-in retry middleware honouring Telegram's retry_after * Generic dispatcher with filters and conversation handlers * Self-verifying codegen pipeline (regen → audit → emit → run tests) * 14 example bots covering common patterns
Examples
Each subdirectory contains a self-contained sample bot demonstrating one feature area.
| Example | What it shows |
|---|---|
| echo | Long-poll bot that echoes text back to the sender |
| webhook | Webhook delivery with secret-token verification |
| callback | Inline keyboard with callback queries and counter state |
| conversation | Multi-step conversation flow with dispatch/conversation |
| files | Upload and download files via api.DownloadFile |
| inline | Inline-mode bot returning search-style results |
| middleware | Custom middleware chains via Router.Use |
| stateful | Per-user state managed via closures |
| welcome | Greet new chat members; detect and log departures |
| moderation | /kick, /ban, /mute, /warn with admin permission checks |
| polls | Create polls and tally answers via OnPollAnswer |
| payments | Telegram Payments: sendInvoice → pre_checkout_query → successful_payment |
| pagination | Multi-page inline keyboard with stateless prev/next navigation |
| admin | Auth middleware allowlisting specific user IDs via Router.Use |
Running
All examples follow the same pattern:
export TELEGRAM_BOT_TOKEN=123456:ABC...
go run ./examples/<name>
Webhook examples need a public HTTPS endpoint (use Cloudflare Tunnel, ngrok, or similar).
Common patterns
Retry-safe HTTP — every example wraps the HTTP client with client.NewRetryDoer, which automatically honours Telegram's retry_after field on 429 responses.
Graceful shutdown — all examples use signal.NotifyContext so the bot drains cleanly on SIGINT/SIGTERM.
Structured logging — for production, wire a logger via client.WithLogger and wrap the process in supervision (systemd unit, k8s liveness probe, etc.).