Telegram Bot API library for Go
[![Telegram Bot API Version][TelegramVersionBadge]][TelegramLastVersion] Telego is a Telegram Bot API library for Golang with full [API][TelegramBotAPI] implementation (one-to-one)
The goal of this library was to create API with the same types and methods as actual Telegram Bot API.
Every type and method have been represented in types.go and methods.go files with mostly
all documentation from Telegram.
For more detailed documentation, see docs at telego.pixelbox.dev.
Note: Telego uses fasthttp instead of
net/httpand go-json instead ofencoding/jsonby default (both can be changed).
Click to show • hide
How to get the library:
go get github.com/mymmrac/telegoMake sure you get the latest version to have all new features and fixes.
More examples can be seen here:
Click to show • hide
Note: Error handling may be missing in examples, but I strongly recommend handling all errors.
Generally, useful information about Telegram Bots and their features:
Click to show • hide
For start, you need to create an instance of your bot and specify token.
…To receive updates, you can use one of two methods:
bot.UpdatesViaLongPolling)bot.UpdatesViaWebhook, recommended way)Let's start from long polling (easier for local testing):
…Webhook example (recommended way):
…For running multiple bots from a single server, see this example.
Tip: For testing webhooks locally, you can use Ngrok to make a tunnel to your localhost, and get a random domain available from the Internet. It's as simple as
ngrok http 8080. Or follow Telego + Ngrok example using ngrok/ngrok-go for most convenient bot testing.
Tip: You may wish to use Let's Encrypt in order to generate your free TLS certificate.
All Telegram Bot API methods described in documentation can be
used by the library. They have the same names and the same parameters, parameters represented by struct with
name: `` + Params. If method doesn't have required parameters nil value can be used as a parameter.
Note:
types.goandmethods.gowere automatically generated from [documentation][TelegramBotAPI], and it's possible that they have errors or missing parts both in comments and actual code. Feel free to report such things.
…In Telego even though you have all types and methods available, it's often not so
convenient to use them directly. To solve this issues telegoutil package was created. It contains
utility-helper function that will make your life a bit easier.
I suggest including it with alias to get cleaner code:
import tu "github.com/mymmrac/telego/telegoutil"The package contains couple methods for creating send parameters with all required parameters like:
Message(chatID, text) => SendMessageParamsPhoto(chatID, photoFile) => SendPhotoParamsLocation(chatID, latitude, longitude) => SendLocationParamsOr other useful methods like:
ID(intID) => ChatIDFile(namedReader) => InputFileUtils related to methods can be found in telegoutil/methods, for
types in telegoutil/types, for handlers in
telegoutil/handler, for api in telegoutil/api.
Note: If you think that something can be added to
telegoutilpackage fill free to create an issue or pull request with desired changes.
With... methodsCreating method parameters is sometimes bulky and not convenient, so you can use with methods in combination with
utility methods.
Here is a simple example of creating a message with a keyboard that has 4 buttons with different parameters.
…Those methods allow you to modify values without directly accessing them, also as you saw with methods can be staked
one to another to update multiple values.
Processing updates just in for loop is not the most pleasing thing to do, so Telego provides net/http like handlers,
but instead of the path, you provide predicates.
One update will only match to the first handler whose predicates are satisfied, predicates checked in order of handler registration (it's useful to first specify the most specific predicates and then more general).
Also, all handlers (but not their predicates) are processed in parallel.
I suggest including it with alias to get cleaner code:
import th "github.com/mymmrac/telego/telegohandler"Here is an example of using handlers with long polling updates.
You can see the full list of available predicates in telegohandler/predicates,
or define your own.
…Just handling updates is useful, but handling specific updates like messages or callback queries in most of the cases is more straightforward and provides cleaner code.
So Telego provides specific handles for all fields of telego.Update. See the list of all available handler types in
telegohandler/handlers, or define your own.
…One more important part of handlers is groups and middlewares. Telego allows creating groups with and without predicates and attaching middleware to groups.
package main
import (
"fmt"
"github.com/mymmrac/telego"
th "github.com/mymmrac/telego/telegohandler"
)
func main() {
// Init ...
// Add global middleware, it will be applied in order of addition
bh.Use(func(ctx *th.Context, update telego.Update) error {
fmt.Println("Global middleware") // Will be called first
return ctx.Next(update)
})
// Create any groups with or without predicates
// Note: Updates first checked by groups and only then by handlers
// (group -> ... -> group -> handler)
task := bh.Group(th.TextContains("task"))
// Add middleware to groups
task.Use(func(ctx *th.Context, update telego.Update) error {
fmt.Println("Group-based middleware") // Will be called second
if len(update.Message.Text) Note: Use `sonic` only on supported platforms as it has its own limitations, more
> [here](https://github.com/bytedance/sonic?tab=readme-ov-file#requirement).
If you wish to set JSON encoding/decoding methods to something custom, there are global methods `SetJSONMarshal` and
`SetJSONUnmarshal` that can be used.
## :art: Contribution
Contribution guidelines listed [here](docs/CONTRIBUTING.md).
## :star: Stargazers over time
> Powered by [caarlos0/starcharts](https://github.com/caarlos0/starcharts)
## :closed_lock_with_key: License
Telego is distributed under [MIT licence](LICENSE).
[TelegramBotAPI]: https://core.telegram.org/bots/api
[TelegramVersionBadge]: https://img.shields.io/static/v1?label=Supported%20Telegram%20Bot%20API&color=29a1d4&logo=telegram&message=v10.3
[TelegramLastVersion]: https://core.telegram.org/bots/api#august-24-2026No open issues yet, or sync has not completed.