tucnak/telebot: a Go bot framework for the Telegram Bot API

What tucnak/telebot solves, and who it is for

The Telegram Bot API is a plain HTTP interface. Every bot needs the same scaffolding around it: a loop that fetches updates, a way to route an update to the right piece of code, and helpers for sending messages, files and keyboards. Telebot is one answer to that scaffolding problem in Go. The README describes it as a bot framework for the Telegram Bot API and says the author deliberately avoided a 1:1 API wrapper, choosing instead to focus on "the beauty of API and performance." That is the design bet: you get a smaller surface than the raw API, and the package decides how routing and file handling should look.

The audience is Go developers. The minimal example in the README is a single main function with a Settings struct, a LongPoller, a Handle call and a Start call. There is no separate build step, no configuration file required, and no runtime beyond Go itself. If your bot is one part of a larger Go service, that matters: you can import the package, register handlers, and keep the rest of your application in the same binary and the same deployment pipeline.

It is not aimed at people who want a visual bot builder or a hosted dashboard. Several of the phrases people search for around this name, such as telebot creator and telebot studio, refer to other products entirely, and nothing in the repository suggests Telebot ships a graphical editor. This is a library, and using it means writing Go.

Routing, Context and middleware: the mechanism

The core mechanism is a handler registry keyed by endpoint constants. The README says the routing system delivers updates to their endpoints, and that there are dozens of supported endpoints listed in the package constants. You register a function against an endpoint such as tele.OnText, tele.OnPhoto, tele.OnChannelPost or tele.OnQuery, and the framework calls it when a matching update arrives. Commands are registered as strings like "/hello" or "/start".

Handlers receive a Context, which the README describes as a type that wraps the update structure and provides helpers for getting at the current event regardless of its kind. Context exposes Sender(), Text(), Message(), Callback() and Args(), plus short-hands such as c.Send(). The distinction between the bot-level methods and the context short-hands is stated directly: use the full bot functions only when you need the result, otherwise prefer the context form.

Middleware is a chain of functions with access to Context, run before the handler. The README shows three scopes. Global middleware is attached with b.Use. Group-scoped middleware comes from b.Group(), and the README's example restricts a group to a whitelist of admin IDs before registering /ban and /kick. Handler-scoped middleware is passed as a third argument to Handle. A custom middleware is just a function that takes a tele.HandlerFunc and returns one, which is a familiar shape for anyone who has written Go HTTP middleware.

The Poller interface is the seam for update delivery. The README defines it as a type with a Poll method that takes the bot, an updates channel and a stop channel, and states that all pollers must implement it. The framework does not care how updates arrive as long as a poller is set or ProcessUpdate is called for each update. That is a clean extension point, and it is also the place where the documentation stops short: the README does not show a webhook poller implementation, only the interface and the long polling default.

Installing tucnak/telebot and sending a first reply

The README gives one install command. It fetches the v4 module path, which matches the module line in go.mod.

go get -u gopkg.in/telebot.v4

After that, the minimal bot from the README is a Settings value with a Token and a LongPoller, followed by NewBot, a Handle call and Start. The token comes from an environment variable in the example, so nothing secret is committed.

package main

import (
	"log"
	"os"
	"time"

	tele "gopkg.in/telebot.v4"
)

func main() {
	pref := tele.Settings{
		Token:  os.Getenv("TOKEN"),
		Poller: &tele.LongPoller{Timeout: 10 * time.Second},
	}

	b, err := tele.NewBot(pref)
	if err != nil {
		log.Fatal(err)
		return
	}

	b.Handle("/hello", func(c tele.Context) error {
		return c.Send("Hello!")
	})

	b.Start()
}

Run the binary with TOKEN set to the value BotFather gave you, then send /hello to the bot in Telegram. You should get the string "Hello!" back. The README notes that the routing system handles delivery, so you do not write the update loop yourself.

Commands can carry arguments. The README shows c.Args() returning a slice split on spaces for a command like /tags tag1 tag2, and c.Message().Payload holding the deep-link payload after /start. For a richer first handler, register tele.OnText and reply with the incoming text using c.Send, which the README presents as the preferred short-hand over b.Send.

The file layer and what it actually saves you

Files are where the framework does the most work on your behalf. The README states that Telegram allows files up to 50 MB, and that Telebot can upload from disk or by URL and download from Telegram. The interesting part is the caching behaviour. When you build a media value with tele.FromDisk("file.ogg"), the value reports OnDisk true and InCloud false. Send it once, and the file is uploaded. Send the same value to another recipient, and the README says Telebot will not re-upload it but will use the Telegram FileID it already obtained, at which point InCloud is true and FileID is populated.

That matters for bots that distribute the same asset to many chats. Re-uploading a 40 MB audio file for every recipient would be wasteful, and the framework handles the transition from local path to cloud identifier for you. The README also says File contains only public fields, so you can marshal and store it in whatever format you like and recover the FileID later. That is a small but practical detail: it means a restart does not force a re-upload if you persist the value.

The limitation is the 50 MB ceiling, which comes from Telegram rather than from the library. Anything larger is not a Telebot problem to solve, and the README does not describe a workaround. The other thing the README does not describe is what happens when an upload fails partway, or how the cached FileID behaves if the underlying file changes on disk. Those are the questions you would want answered before relying on the cache in production.

Where Telebot is the wrong choice

The clearest gap is webhooks. The README presents the Poller interface and states that Telebot does not care how updates are provided, but it does not document a webhook poller or show one being configured. Long polling is the documented path. If your deployment model requires inbound HTTPS with a registered webhook, you are working from the interface definition and whatever exists in the repository, not from a worked example in the README.

Licensing is the second thing to check before adopting. The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not map the LICENSE file to a known identifier. The README has a License section but the text available here does not include its contents. That is not a statement that the licence is restrictive; it is a statement that you cannot tell from the summary. Read LICENSE in the repository root yourself and decide whether its terms fit your project. Nothing here is legal advice.

Third, the name is crowded. Searching for telebot returns questions about Python installation, Termux, aiogram comparisons and a product called Telebot Creator. If you are looking for a Go library, most of what you find under this name will be about something else. That is a discovery problem rather than a technical one, but it costs time when you are evaluating options.

Finally, the project is not a general Telegram client. The README frames it around bot endpoints, and the repository entries are bot-oriented files. If you need to act as a user account rather than a bot, this is not the tool.

How it compares with the Python bot libraries

The most common comparison drawn in search is between this project and Python frameworks such as pyTelegramBotAPI and aiogram. The difference is not feature parity, it is the host language and the concurrency model. In Go, a handler returns an error and the framework decides what to do with it; the middleware chain is a function that wraps a handler function. In Python, the equivalent layers are decorators and async coroutines. If your team writes Go, the Python libraries are not alternatives in any practical sense, because adopting one means running a second service in a second language.

Within Go, the meaningful comparison is between using Telebot and writing a thin wrapper over the Bot API yourself. The README's own framing is that it is not a 1:1 wrapper. What you get for the dependency is command routing with group syntax handling, the Context abstraction, the middleware chain, and the file upload cache. What you give up is control over exactly how updates are fetched and dispatched, unless you implement the Poller interface yourself. The go.mod file lists three dependencies, including viper and a YAML library, which is worth noting if you care about the transitive dependency graph of a small bot.

One comparison the search data raises but cannot settle is against Telethon. Telethon is a client library for the Telegram API aimed at user accounts as well as bots, and the README here says nothing about user-account operation, so there is no basis for a feature-by-feature comparison.

Maintenance, versions and upgrade cost

The repository is not archived, and the last push was on 2026-06-16, which is recent enough that the branch is receiving changes. That said, the release list tells a different story about tagged versions: v3.3.6 is dated 2024-06-10, v3.2.0 is dated 2023-11-20, and v3.1.0 is dated 2022-10-06. The default branch is v4, so development and the module path have moved to a major version that does not appear in the release list. If you pin to a tagged release, you may be pinning to the v3 line while the branch you are reading on GitHub is v4.

That gap is the main upgrade cost to plan for. The import path in the README and in go.mod is gopkg.in/telebot.v4, so v4 is the version the documentation describes. Anyone on v3 who wants the documented API is looking at a major-version migration, and the README does not include a migration guide. Check the repository for release notes before assuming the move is mechanical.

The go.mod declares go 1.16 and requires github.com/goccy/go-yaml v1.9.5, github.com/spf13/viper v1.13.0 and github.com/stretchr/testify v1.8.0. The testify dependency is a test dependency. Viper and the YAML library are heavier than most bots need, so if dependency count matters to you, that is a real consideration rather than a theoretical one. On licensing, the metadata reports NOASSERTION, so read LICENSE directly and confirm the terms before you ship.

Editorial conclusion

Adopt tucnak/telebot if your bot already lives in a Go codebase and you want routing, middleware and file handling in one package rather than a hand-rolled API wrapper. Skip it if you need a documented webhook setup, a permissive licence you can confirm from the repository, or Python-side tooling, since the search results for this name mostly point at unrelated Python projects. Before committing, read LICENSE in the repository root, check whether v4 is the branch you want to track, and confirm that the Poller interface matches how you intend to receive updates.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. tucnak/telebot on GitHub