Telego: a Telegram Bot API client that mirrors the API one to one

A mirror, deliberately

Telego is a Telegram Bot API library for Go with a full one-to-one implementation of the API, and the goal is stated plainly: to create an API with the same types and methods as the actual Telegram Bot API.

Every type and method has been represented in `types.go` and `methods.go` with mostly all the documentation from Telegram. That is the whole design, and it is a design with a clear benefit and a clear cost.

The benefit is that a developer who knows the Telegram Bot API from the documentation knows Telego, because the names are the same and the documentation is the same. There is no translation layer to learn, no idiomatic rename of a method, and no question about whether a call is supported, because the answer is that the method exists if Telegram has it. For a bot that uses an unusual corner of the API, that is a real advantage over a smaller library with its own vocabulary.

The cost is that the library tracks the upstream API closely, and the release history shows it. Version 1.12.0 is titled Telegram Bot API v10.3 and was published on 2026-08-29, and the two releases around it are bug fixes, v1.12.1 fixing unmarshaling on the same day and v1.11.2 with an unmarshal fix on 2026-08-19. The fix titles are the giveaway, since unmarshaling is where a mirror of a JSON API breaks when the upstream changes a payload.

The project is MIT licensed, the primary language is Go, the default branch is `main`, and the last push was on 2026-10-13. The documentation is published at `telego.pixelbox.dev`, and the repository has a DeepWiki page as well as a Telegram chat for questions.

fasthttp and a JSON library that is not the standard one

There is one note in the README that changes the character of the library, and it is easy to skim past.

Telego uses fasthttp instead of `net/http` and go-json instead of `encoding/json` by default, and both can be changed.

The `net/http` substitution is the more consequential of the two. The standard library client is built around a connection pool with a particular behaviour around timeouts, keep-alives and proxies, and fasthttp is a different implementation with different trade-offs, typically chosen for throughput. For a bot, which makes a modest number of long-lived API calls, the case for that choice is not obvious from the outside, and the practical consequence is that a team that has tuned a deployment for `net/http` semantics, or that has a proxy in front of its traffic, has to check that the behaviour matches.

The JSON substitution is more delicate, because the `go.mod` shows that the default is not the upstream go-json package at all:

require (
	github.com/bytedance/sonic v1.15.4
	github.com/stretchr/testify v1.12.1
	github.com/valyala/fasthttp v1.75.0
	github.com/valyala/fastjson v1.6.10
	go.uber.org/mock v0.6.0
)

The file also carries a commented line for the original go-json package and a note that it is a temporary fix for an issue in that project, with a different fork, `github.com/grbit/go-json` at v0.11.0, required in its place. So the default JSON implementation of the library is a community fork that was adopted to work around a bug in the package everyone else uses, and the upstream dependency is commented out rather than removed.

That is the kind of detail a reviewer should read twice. It is not a criticism, the fix was applied and the reason is documented in the file, but it means the JSON behaviour of the library is not the JSON behaviour of the ecosystem, and the version numbers of the fork are not the version numbers of the thing it forked.

Long polling and webhooks, both first class

Receiving updates is where a bot library earns its keep, and Telego supports both mechanisms with a dedicated example for each.

The long polling approach has its own file in the repository, `long_polling.go`, and examples for long polling and for graceful shutdown in long polling mode. The webhook side has `webhook.go` and `webhook_handler.go`, with examples for webhooks, for a webhook reached through ngrok, and for graceful shutdown in webhook mode.

The ngrok example matters more than it looks. A webhook needs a public HTTPS address, and a developer on a laptop does not have one, so the example shows the tunnel in the loop. It is a small piece of documentation that saves a lot of confusion the first time.

There is also a multi bot webhook example, in two flavours, one using the standard library and one using Fiber, which is worth noting because it means a server that already runs a framework can host several bots from one process rather than running one binary per bot.

And there is a retry caller example, which addresses the failure mode every bot has: a request to Telegram fails because of a network blip, and a bot that does not retry loses the update. Whether the retry policy is in the library or in the caller's code is a design question, and the presence of the example suggests the answer is that the caller composes it.

The graceful shutdown examples come in three variants, with no helpers, with long polling and with a webhook, which is a reasonable amount of care for a library that runs in a process someone has to stop.

The handler layer, and the examples that double as documentation

The `telegohandler/` package is the part of Telego that goes beyond the API mirror, and it is what turns a set of methods into a bot framework lite.

The examples list shows what it contains. There are bot handlers with groups and middleware, with a context carrying the update, with custom predicates for handlers, with handler ordering, with specific handlers, and an update processor. There is a conversation bot described as a state machine, which is the way to write a bot that has to remember what the user said three messages ago.

The distinction between a method library and a handler layer is the difference between calling `sendMessage` and having the library route an incoming update to the right function. The second is what removes the boilerplate from a bot, and Telego offers it without making it the only way to use the library.

The example set is unusually complete for a Go library, and it is the documentation. There is a basic example, a configuration example, a methods example, and then one directory per feature: sending files, downloading files, inline keyboard, keyboard, rich text, edit message, utility methods, inline query, message entity, menu bot, web apps for Mini Apps, multi bot webhook, and a test server. There is an echo bot in three variants, plain, with handlers, and one hosted as a separate repository with handlers, a webhook and graceful shutdown in Docker.

The one caveat the README gives about the examples is worth repeating: error handling may be missing in examples, and the author strongly recommends handling all errors. That is a fair warning, since an example that ignores an error teaches the reader to ignore it.

The example directory has its own `go.mod` and `go.sum`, so the examples are a separate module, which keeps their dependencies out of the library's own module graph and lets them depend on things the library does not.

Types, setters, utilities and the toolchain around them

The rest of the repository is a set of conventions that a library of this kind needs, and they are visible in the file names.

There are `types.go` and `types_setters.go` on one side, and `methods.go` and `methods_setters.go` on the other. The setters files are where the helper `With...` methods live, and the table of contents in the README calls them out as a section of their own. A setter method is the idiomatic Go way of building an optional-parameter struct without an options pattern, so the `With...` helpers are how a request with optional fields is assembled.

There is a `telegoutil/` package for utility methods, `json.go` for the JSON handling that the earlier section is about, and a `logger.go` for logging. The `telegoapi/` directory holds the API definitions, and `internal/` holds what the library does not expose. On top of that sit `bot.go` and `bot_options.go`, which is where the bot is constructed and configured, and the documentation mentions a build configuration section in the guide.

The toolchain is where a reader can see how the project is run. The `go.mod` names Go 1.26.7 and the dependency set is short, with fasthttp, fastjson, the JSON library, the test framework and a mocking library. The mocking library matters more than it looks, because the whole point of the `bot_options.go` and `telegoapi/` split is that the transport can be replaced, and a mock is how you test a bot without talking to Telegram.

The CI setup is described by the badges: a build workflow, a separate race testing workflow, a SonarCloud quality gate with coverage, code smells and lines of code, a Go report card, and a golangci-lint configuration in the repository. A `Taskfile.yml` holds the developer tasks, and `sonar-project.properties` holds the analysis configuration.

Where telego is the wrong tool

The limits follow from the mirror design and from the transport choice, and they are worth naming before a team commits.

The first is the maintenance tail. A library that mirrors an upstream API one to one has to follow every upstream release, and the version numbers here, 1.12.0 for Telegram Bot API v10.3, show the coupling directly. A team that wants stability will take a pinned version and then find that a new Telegram feature is not available until the library catches up, and a team that wants the newest feature will take a floating version and take the upgrade risk on every dependency bump. There is no third option, and that is the cost of the approach.

The second is the transport default. The fasthttp substitution is the kind of decision that is invisible until it is not, because the standard library's HTTP client has well known behaviour around connection reuse, header handling and proxying, and code written against it does not always behave the same way against another implementation. The library does say both can be changed, which is the right mitigation, but it means the default configuration is not the one most Go code is written against.

The third is the JSON fork. A bug workaround that swaps a widely used package for a fork of it is a reasonable response to a broken release, and it is also a dependency that a team has to track separately, and the fix is described as temporary in a comment that is still in the file. The second thing to check is what the library does with a payload that the upstream API has just changed, which is where the unmarshal fixes in the recent release notes came from.

The alternative is a higher level bot framework, which gives you update routing, state and dialogue management without a one-to-one API surface, and which is the right choice for a bot that is mostly conversation. The difference in approach is that Telego is the API with a thin handler layer attached, and a framework is the runtime with the API hidden inside it, so the first is easier to reason about when the Telegram API itself is the problem you are solving, and the second is easier when the conversation is.

Editorial conclusion

Telego fits a Go team that wants the Telegram Bot API as a typed Go surface, with the upstream documentation attached to every method, and that would rather poll or receive webhooks than adopt a bot framework that imposes its own shape. It is the wrong choice for a project that wants a higher level bot framework, and it is a decision with a maintenance tail, because a library that mirrors an upstream API one to one has to follow every upstream release. Before adopting it, check the `go.mod` for the Go version you run and for the JSON library, since the default is a fork rather than the standard package, and read the configuration section in the documentation to see whether you want the fasthttp transport or the standard one.

Frequently asked questions

Official sources

1. License: MIT
2. mymmrac/telego on GitHub
3. Project website
4. README
5. Releases