gotgbot: a generated Go wrapper for the Telegram bot API

The API surface is generated from a spec, not typed by hand

gotgbot is a code-generated wrapper for the Telegram bot API, heavily inspired by the python-telegram-bot library. The distinction that defines the project is where the code comes from.

All the Telegram types and methods are generated from a bot API specification maintained in a separate repository, PaulSonOfLars/telegram-bot-api-spec, and the output lands in the gen_*.go files at the root of the repository. The library therefore does not have a hand written type per Telegram concept, and the readme lists the consequences as three properties: the library is guaranteed to match the docs, it is easy to update, and it is self-documenting because it re-uses the pre-existing Telegram documentation.

That guarantee is worth understanding precisely. It is a guarantee about the library matching the specification, not a guarantee that the specification matches the server. When Telegram adds a field, the spec changes, the code is regenerated, and the new field appears. There is no hand written layer to fall out of sync, and there is also no hand written layer where a maintainer might add a convenience the docs do not describe.

The type safety claim follows from the same mechanism. The readme states there is no weird interface{} logic and that all types match the bot API docs, which is a direct consequence of generating structs from the spec instead of decoding into maps.

The dependency story is equally deliberate: no third party library bloat, and the package uses only the standard library.

Updates run in their own goroutine and panics are recovered

The extensions package is what turns the generated wrapper into something you build a bot with, providing an updater and dispatcher pattern for update processing out of the box.

The concurrency model is described in one line and it is the design decision that matters most for a bot library. Each update is processed in its own goroutine, which encourages concurrent processing and keeps the bot responsive. Without that, one slow handler blocks every other update, which is the classic way a Telegram bot falls over under load.

The second guarantee is about failure. The readme states that code panics are automatically recovered from and logged, avoiding unexpected downtime. For a long running bot, a panic in a handler would otherwise take down the process, and a bot that is down stops answering, which for a deployed service is the difference between a bug and an outage.

The trade-off is the usual one. Recovering and logging means a panicking handler fails silently for the user who triggered it unless you watch the logs, and goroutine per update means you have to be careful about your own shared state. That is what the stateful client sample is for.

The recommended samples show the intended progression. The command bot is there to explore basic use of commands, the webhook bot to set up webhooks, and the stateful client bot to pass shared data around without global variables. The samples directory goes wider than that, with callback query, conversation, echo, inline query, metrics, middleware, payments and webapp bots alongside the three highlighted ones.

Getting it into a project is one go get

The installation is the standard Go tool:

go get github.com/PaulSonOfLars/gotgbot/v2

Note the major version in the import path. The module declares its path as github.com/PaulSonOfLars/gotgbot/v2 in go.mod, with go 1.24 as the language version, and the default branch of the repository is named v2 rather than master. That combination of a v2 module path and a version-named branch follows the Go module conventions for a project that has broken compatibility with its v1 line.

The package documentation is published on pkg.go.dev at the same module path, so the godoc for the generated types is where you will spend most of your time. The generated names follow the Telegram documentation, which means searching for a Telegram method name usually finds the Go method with the same name.

The supporting packages are in the ext/ directory and are imported under the same module, so the extensions package that gives you the updater and dispatcher lives alongside the generated API rather than in a separate module. That matters for versioning, since a single go get brings both.

For questions there is a Telegram support chat linked from the readme, which is the faster route than opening an issue when you are unsure whether something is a library behaviour or a misunderstanding of the bot API.

Regenerating the code is the maintainer workflow

For contributors, the interesting part of the repository is the generation pipeline, and it is described precisely enough to be reproduced.

If you have changed the code generation itself, you need to regenerate the library code, which is done by running go generate from the repository root. That generates the code from the specification repository at the commit pinned in the spec_commit file, which is a file at the root of the repository for exactly that purpose.

Upgrading is a separate, explicit step. To move the pinned commit forward and regenerate against it, you run GOTGBOT_UPGRADE=true go generate. That fetches the latest commit sha from the spec repository and regenerates the library against it, giving the latest available version of the API.

The two-step design is deliberate. A plain go generate is reproducible, since it always uses the pinned commit, while the upgrade variant is the one that moves the pin. Without that separation, every regeneration would silently pull in upstream changes, and a diff against the previous generated code would mix your change with whatever Telegram published that week.

The file layout makes the generation visible from the top level. gen_consts.go, gen_helpers.go, gen_methods.go and gen_types.go are the generated outputs, and alongside them sit the hand written files: bot.go, request.go, sender.go, file.go, entities.go, custom_types.go, custom_consts.go and custom_helpers.go, plus the formatting files richtext.go, richtext_html.go and richtext_markdown.go. The custom_ prefix marks the parts a maintainer wrote by hand on top of the generated surface.

The v2 line is still in release candidate

The maintenance picture is where a reader needs to look carefully before depending on this.

The three most recent tags are v2.0.0-rc.37 from 2026-10-17, v2.0.0-rc.36 from 2026-08-02 and v2.0.0-rc.35 from 2026-05-25. Every one of them is a release candidate for 2.0.0, and there is no 2.0.0 final in the list. The repository is not archived, and the last push was on 2026-10-17, the same day as the newest candidate.

The release cadence is regular enough to be predictable, with candidates roughly every two to three months. That regularity says the project is alive and the v2 work is being done in public, but it also says the API surface is still moving. A candidate number rising to rc.37 without a final release is a pattern that usually means there is a long tail of small changes still landing on the v2 branch, each of which is individually reasonable and collectively a moving target.

The licence is MIT with the LICENSE file at the root, and the CI setup includes a golangci.yaml configuration, so linting is part of the build. The go.sum and go.mod files are minimal, consistent with the no third party dependency claim, and there is a scripts/ directory for the tooling around generation.

For an adopter, the practical position is that you should pin an exact candidate version rather than track the branch, and expect to read the diff between candidates when you upgrade.

Editorial conclusion

gotgbot suits a Go developer writing a Telegram bot who wants typed API calls that match the current documentation without pulling in a dependency tree, and who is willing to read generated code. It does not suit a team that needs a stable 1.x release, because every recent tag is a v2.0.0 release candidate, and it does not suit anyone who expects hand written, hand maintained API code. Before adopting it, run go get for the v2 module path, confirm your bot only needs standard library dependencies, and look at the command, webhook and stateful client samples before writing your own dispatcher.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PaulSonOfLars/gotgbot on GitHub
4. README
5. Releases