Telego • Go Telegram Bot API

[![Telegram Bot API Version][TelegramVersionBadge]][TelegramLastVersion] <br>

<br>

<p align="center"> <img src="docs/logo/telego-long.png" alt="Telego logo" width="512px" style="border-radius: 12px;"> </p>

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/http and go-json instead of encoding/json by default (both can be changed).

:clipboard: Table Of Content

<details> <summary>Click to show • hide</summary>

• :zap: Getting Started
  • :jigsaw: Basic setup
  • :envelope_with_arrow: Getting updates
  • :kite: Using Telegram methods
  • :soap: Utility methods
  • :mechanical_arm: Helper With... methods
  • :sun_behind_large_cloud: Bot handlers
  • :gear: Build configuration
• :art: Contribution
• :star: Stargazers over time
• :closed_lock_with_key: License

</details>

:zap: Getting Started

How to get the library:

go get github.com/mymmrac/telego

Make sure you get the latest version to have all new features and fixes.

More examples can be seen here:

<details> <summary>Click to show • hide</summary>

• Basic
• Configuration
• Methods
• Updates (long polling)
• Updates (webhook)
• Ngrok webhook
• Echo bot
• Echo bot (with handlers)
• Echo bot (handlers + webhook + graceful shutdown + docker)
• Conversation bot (state machine)
• Sending files (documents, photos, media groups)
• Downloading files
• Inline keyboard
• Keyboard
• Edit message
• Utility methods
• Inline query bot
• Bot handlers
• Bot handles (groups + middleware)
• Update's context
• Graceful shutdown (no helpers)
• Graceful shutdown (long polling)
• Graceful shutdown (webhook)
• Custom predicates for handlers
• Handler ordering
• Specific handlers
• Update processor
• Message entities
• Multi bot webhook
• Multi bot webhook (using Fiber)
• Retry caller
• Menu bot
• Test server
• Web Apps (Mini Apps)

</details>

Note: Error handling may be missing in examples, but I strongly recommend handling all errors.

Generally, useful information about Telegram Bots and their features:

<details> <summary>Click to show • hide</summary>

• :page_facing_up: Telegram Bot API • Telegram documentation of Bot API (full reference)
• :jigsaw: Telegram Bot Fundamentals • Bots: An introduction for developers
• :star2: Telegram Bot Features • Describes individual bot elements and features in detail
• :headphones: Telegram Bot Webhooks • Marvin's Marvellous Guide to All Things Webhook
• :moneybag: Telegram Bot Payments • Describes payment system and payment lifecycle
• :iphone: Telegram Bot WebApps • Describes WebApps and interactions with them
• :link: Ngrok • Connect localhost to the Internet
• :shield: Let's Encrypt • TLS certificates for free

</details>

:jigsaw: Basic setup

▲ Go Up ▲

For start, you need to create an instance of your bot and specify token.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/mymmrac/telego"
)

func main() {
	// Get Bot token from environment variables
	botToken := os.Getenv("TOKEN")

	// Create bot and enable debugging info
	// Note: Please keep in mind that default logger may expose sensitive information,
	// use in development only
	// (more on configuration in examples/configuration/main.go)
	bot, err := telego.NewBot(botToken, telego.WithDefaultDebugLogger())
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// Call method getMe (https://core.telegram.org/bots/api#getme)
	botUser, err := bot.GetMe(context.Background())
	if err != nil {
		fmt.Println("Error:", err)
	}

	// Print Bot information
	fmt.Printf("Bot user: %+v\n", botUser)
}

:envelope_with_arrow: Getting updates

▲ Go Up ▲

To receive updates, you can use one of two methods:

• using long polling (bot.UpdatesViaLongPolling)
• using webhook (bot.UpdatesViaWebhook, recommended way)

Let's start from long polling (easier for local testing):

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/mymmrac/telego"
)

func main() {
	botToken := os.Getenv("TOKEN")

	// Note: Please keep in mind that default logger may expose sensitive information,
	// use in development only
	bot, err := telego.NewBot(botToken, telego.WithDefaultDebugLogger())
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// Get updates channel
	// (more on configuration in examples/updates_long_polling/main.go)
	updates, _ := bot.UpdatesViaLongPolling(context.Background(), nil)

	// Loop through all updates when they came
	for update := range updates {
		fmt.Printf("Update: %+v\n", update)
	}
}

Webhook example (recommended way):

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

	"github.com/mymmrac/telego"
)

func main() {
	ctx := context.Background()
	botToken := os.Getenv("TOKEN")

	// Note: Please keep in mind that default logger may expose sensitive information,
	// use in development only
	bot, err := telego.NewBot(botToken, telego.WithDefaultDebugLogger())
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// Set up a webhook on Telegram side
	_ = bot.SetWebhook(ctx, &telego.SetWebhookParams{
		URL:         "https://example.com/bot",
		SecretToken: bot.SecretToken(),
	})

	// Receive information about webhook
	info, _ := bot.GetWebhookInfo(ctx)
	fmt.Printf("Webhook Info: %+v\n", info)

	// Create http serve mux
	mux := http.NewServeMux()

	// Get an update channel from webhook.
	// (more on configuration in examples/updates_webhook/main.go)
	updates, _ := bot.UpdatesViaWebhook(ctx, telego.WebhookHTTPServeMux(mux, "/bot", bot.SecretToken()))

	// Start ser