Framework
tucnak/telebot avatar
tucnak/telebot

Telebot: routing, middleware and pollers for the Telegram Bot API in Go

Telebot is a Telegram bot framework in Go.

4,633 stars527 forksGoNOASSERTION

At a glance

What is it?
Telebot is a Go framework for the Telegram Bot API built around command routing, middleware at three scopes, a Poller interface you can replace, and file reuse through Telegram FileIDs. The catch is in the versioning: the module path is v4 while the newest release tag is still v3.3.6 from June 2024.
Who is it for?
Telebot suits a Go developer who wants a small, readable bot and is comfortable reading the source when the API reference runs out, since the repository is organised one file per area of the Bot API. It does not suit a team that wants a tagged release of the v4 line, because no v4 release appears among the recent releases, or one that needs published performance evidence for a highload claim the README states without numbers.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 8 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tucnak/telebot4,633 ★ · -2
Star history
Repository2026-09-232026-11-15
tucnak/telebot4.6k4.6k

-2 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A module path, a token and a LongPoller are the whole setup

The install is one line:

bash
go get -u gopkg.in/telebot.v4

The smallest working bot reads its token from the environment, picks a poller, registers one handler and starts:

go
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()
}

Three details carry most of the weight. `tele.Settings` takes the `Token` and the `Poller`, so the credential never sits in source. `&tele.LongPoller{Timeout: 10 * time.Second}` sets the window the framework holds open while waiting for updates, and ten seconds is a choice you can change. `b.Start()` blocks, which is why the handler is registered before it and why a real service has to keep that call alive. The import is aliased to `tele` in the example, which matters more than it looks: the module path is versioned, so a v3 dependency and a v4 dependency in the same binary need distinct aliases.

Routing keys off endpoint constants, not raw update types

Handlers attach to endpoints rather than to a switch over update types. A literal command goes to `b.Handle("/hello", ...)`, while update kinds use constants such as `tele.OnText`, `tele.OnChannelPost` and `tele.OnPhoto`. Inside a handler you receive a `tele.Context`, a type that wraps the whole update structure and exposes helpers for the pieces you actually want: `c.Sender()` for the user, `c.Text()` for the body, `c.Message()` for the full message and `c.Message().Photo` for the attachment. The point of that wrapper is that the same helper works no matter which kind of update arrived, so you are not unwrapping four different structs to find the chat. The page notes there are dozens of supported endpoints in the package constants, and describes the routing system as extensible, meaning new endpoints can be added without breaking backwards compatibility. The README's `OnText` example handles all the text messages that weren't captured by existing handlers.

Middleware attaches at three different scopes

Middleware here is a chained function with access to `Context`, called before the handler runs. The scopes are the interesting part, since the same mechanism attaches globally, to a group, or to one handler:

go
// Global-scoped middleware:
b.Use(middleware.Logger())
b.Use(middleware.AutoRespond())

// Group-scoped middleware:
adminOnly := b.Group()
adminOnly.Use(middleware.Whitelist(adminIDs...))
adminOnly.Handle("/ban", onBan)
adminOnly.Handle("/kick", onKick)

// Handler-scoped middleware:
b.Handle(tele.OnText, onText, middleware.IgnoreVia())

The package lives at `gopkg.in/telebot.v4/middleware`. `middleware.Logger()` and `middleware.AutoRespond()` at the top level apply to every endpoint. `b.Group()` creates a scoped set of handlers, which is how an admin area is built: the group takes `middleware.Whitelist(adminIDs...)` and the guarded commands hang off that group instead of off the bot. Passing middleware as a trailing argument to `b.Handle` narrows it to a single endpoint. Writing your own means wrapping `tele.HandlerFunc`:

go
// AutoResponder automatically responds to every callback update.
func AutoResponder(next tele.HandlerFunc) tele.HandlerFunc {
    return func(c tele.Context) error {
        if c.Callback() != nil {
            defer c.Respond()
        }
        return next(c) // continue execution chain
    }
}

That answers callbacks by deferring `c.Respond()` whenever `c.Callback()` is not nil, then calling `next(c)` to keep the chain going. The cost is that order becomes load bearing, and a whitelist check registered after a handler has already replied is too late to stop it.

The Poller interface is three parameters and a stop channel

Telebot does not care how updates reach it, as long as something implements the `Poller` interface or you call `ProcessUpdate` for each update yourself:

go
// Poller is a provider of Updates.
//
// All pollers must implement Poll(), which accepts bot
// pointer and subscription channel and start polling
// synchronously straight away.
type Poller interface {
    // Poll is supposed to take the bot object
    // subscription channel and start polling
    // for Updates immediately.
    //
    // Poller must listen for stop constantly and close
    // it as soon as it's done polling.
    Poll(b *Bot, updates chan Update, stop chan struct{})
}

Three obligations are encoded in that signature. The bot pointer and the updates channel mean the framework owns delivery and your poller only produces. Polling starts synchronously and immediately, so `Poll` is expected to run when called rather than deferring work to a background task. And the stop channel is a contract rather than a suggestion: a poller must keep listening for it and close it as soon as it is finished, which is what lets a process shut down without a goroutine left reading from the API. `tele.LongPoller` with a ten second timeout is the implementation used in the setup example. Writing your own means accepting that obligation, and it is also the place where a queue or a different transport would sit between your source and the bot.

Command parsing keeps two bots out of each other's messages

Commands work both as `/command` and in the group-like form `/command@botname`, and the framework filters on it: a bot never receives a message addressed to another bot, and that holds even when privacy mode is switched off in the bot's settings. For anyone running several bots in one chat, that is the difference between a clean log and constant cross talk, and you do not have to write the check yourself. Deep links get a shortcut too, with `/start <PAYLOAD>` arriving as `c.Message().Payload`:

go
// Command: /start <PAYLOAD>
b.Handle("/start", func(c tele.Context) error {
    fmt.Println(c.Message().Payload) // <PAYLOAD>
})

Arguments after the command name come from `c.Args()`, a list split on spaces, so `/tags one two three` yields three entries:

go
// Command: /tags <tag1> <tag2> <...>
b.Handle("/tags", func(c tele.Context) error {
    tags := c.Args() // list of arguments splitted by a space
    for _, tag := range tags {
        // iterate through passed arguments
    }
})

Both are plain field and method access, with no parsing layer of your own to maintain.

A file uploads once and is then remembered by its FileID

Telegram allows files up to 50 MB in size, and the framework wraps uploading from disk or by URL and downloading from Telegram. The behaviour worth knowing about is what happens on the second send:

go
a := &tele.Audio{File: tele.FromDisk("file.ogg")}

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // false

// Will upload the file from disk and send it to the recipient
b.Send(recipient, a)

// Next time you'll be sending this very *Audio, Telebot won't
// re-upload the same file but rather utilize its Telegram FileID
b.Send(otherRecipient, a)

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // true
fmt.Println(a.FileID) // <Telegram file ID>

`tele.FromDisk("file.ogg")` builds a file that knows it is local, which `a.OnDisk()` reports as true and `a.InCloud()` as false. After the first send, `a.InCloud()` turns true while `a.OnDisk()` stays true, since the path on disk has not gone anywhere. The second send to a different recipient reuses `a.FileID` instead of uploading again, which is what stops a bot from spending its upload budget every time the same asset goes out. Because a `File` contains only public fields, you can marshal one into your own storage and restore it later. The 50 MB ceiling belongs to Telegram rather than to the framework.

The module path says v4 while the newest release tag says v3

The import path is `gopkg.in/telebot.v4` and the default branch is `v4`, yet the three most recent releases are v3.3.6 from 10 June 2024, v3.2.0 from 20 November 2023 and v3.1.0 from 6 October 2022. No v4 release appears in that list. The last commit on the default branch is dated 16 June 2026 and the repository is not archived, so the code is moving while the tags are not. Anyone choosing a version has to decide between a tag and a commit knowingly: a tag gives you v3, the branch gives you unreleased v4. The module file declares `go 1.16` as its language floor and requires three modules directly, `github.com/goccy/go-yaml`, `github.com/spf13/viper` and `github.com/stretchr/testify`, the last of which is the test dependency. That floor is worth checking against the Go version in your build image before anything else.

The highload claim arrives without any numbers

Two kinds of claim sit on the project's front page and only one of them is checkable. The design claims are visible in the API: a concise surface, command routing, middleware, a transparent file API and easy callbacks. The performance claim is not quantified. The page says to consider Telebot a highload ready solution and that the author will test and benchmark the most popular actions, which is a statement of intent rather than a published result. The coverage badge links out to a service instead of showing a table. The rest of the pointers are thin in the same way: there is no project homepage, the API reference is godoc, and the community links are a Telegram channel and the CI badge. The repository layout is one Go file per area of the Bot API, with `chat.go`, `inline.go`, `markup.go`, `payments.go`, `poll.go`, `gifts.go` and `giveaway.go` among them, plus `middleware/`, `react/` and `layout/` as subpackages. Reading that source is a fair way to check a claim the page leaves open.

Editorial conclusion

Telebot suits a Go developer who wants a small, readable bot and is comfortable reading the source when the API reference runs out, since the repository is organised one file per area of the Bot API. It does not suit a team that wants a tagged release of the v4 line, because no v4 release appears among the recent releases, or one that needs published performance evidence for a highload claim the README states without numbers. Before you commit, check three things: whether the commit you pin includes the endpoints you need, what Go version your build image actually has against the declared 1.16 floor, and how your process handles shutdown, because the Poller contract puts the responsibility for the stop channel on your implementation. If you run several bots in one chat, the botname filtering already saves you the work.

Frequently asked questions

How do I install the telebot library for Go?

Fetch the module into your Go project with go get -u gopkg.in/telebot.v4, then import it aliased, for example tele "gopkg.in/telebot.v4". Read the bot token from an environment variable and pass it in tele.Settings together with a Poller.

How do I use telebot to write my first bot?

Build a tele.Settings with a Token and a Poller such as &tele.LongPoller{Timeout: 10 * time.Second}, create the bot with tele.NewBot, register a handler with b.Handle("/hello", func(c tele.Context) error { return c.Send("Hello!") }), and call b.Start(). Endpoints such as tele.OnText, tele.OnChannelPost and tele.OnPhoto catch non command updates.

What is a telebot in the Go ecosystem?

Telebot is a bot framework for the Telegram Bot API written in Go. It provides command routing, middleware, a Poller interface for delivering updates, keyboards, inline query handling and callbacks, plus a file layer that reuses Telegram FileIDs to avoid re-uploading.

Official sources

  1. Issues
  2. README
  3. Releases
  4. tucnak/telebot on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tucnak-telebot.svg)](https://hysenlabs.com/projects/tucnak-telebot)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tucnak-telebot.svg)](https://hysenlabs.com/projects/tucnak-telebot)

Was this useful?