telego Documentation

Telego is a Telegram Bot API library for Golang that provides a one-to-one implementation of the official Telegram Bot API. It aims to mirror the actual Telegram Bot API's types and methods exactly.

Key technical details:

• Core types and methods are defined in types.go and methods.go.
• By default, it uses fasthttp instead of net/http and go-json instead of encoding/json for high performance, though these can be changed.

The telegoutil package (aliased as tu) provides helper functions to simplify the creation of complex Telegram parameter structs.

Common utility methods include:

• Message(chatID, text) => SendMessageParams
• Photo(chatID, photoFile) => SendPhotoParams
• Location(chatID, latitude, longitude) => SendLocationParams
• ID(intID) => ChatID
• File(namedReader) => InputFile

Utility sub-packages:

• telegoutil/methods: Methods helpers
• telegoutil/types: Types helpers
• telegoutil/handler: Handler helpers
• telegoutil/api: API helpers

import tu "github.com/mymmrac/telego/telegoutil"

// Example usage:
msg := tu.Message(
	tu.ID(123),
	"Hello World",
)

Telego provides access to all Telegram Bot API methods. Methods follow the pattern <MethodName> and accept a parameter struct named <MethodName>Params. If a method has optional parameters, you can pass nil for the parameter struct.

// Example: Sending a message using the SendMessage method
// and telegoutil for easier parameter construction.
import (
	"context"
	"github.com/mymmrac/telego"
	tu "github.com/mymmrac/telego/telegoutil"
)

// ... inside main
// bot.SendMessage(ctx, tu.Message(tu.ID(chatID), "text"))

To use Telego in your Go project, install it using go get:

go get github.com/mymmrac/telego

If you discover a security vulnerability, report it immediately using one of the following methods:

1. GitHub Security Advisories: Use the security tab.
2. GitHub Issues: Create an issue at https://github.com/mymmrac/telego/issues.
3. Direct Contact: Contact the maintainer via email or other communication channels.

To initialize a bot, use telego.NewBot with your Telegram Bot token. You can optionally enable debugging information using telego.WithDefaultDebugLogger(). Note that the default logger may expose sensitive information and should only be used during development.

After initialization, you can call Telegram methods like GetMe to verify the bot's identity.

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
	bot, err := telego.NewBot(botToken, telego.WithDefaultDebugLogger())
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// Call method getMe
	botUser, err := bot.GetMe(context.Background())
	if err != nil {
		fmt.Println("Error:", err)
	}

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

Long polling is the easiest method for receiving updates, making it ideal for local testing. Use bot.UpdatesViaLongPolling to get a channel of updates.

package main

import (
	"context"
	"os"

	"github.com/mymmrac/telego"
)

func main() {
	botToken := os.Getenv("TOKEN")
	bot, err := telego.NewBot(botToken)
	if err != nil {
		os.Exit(1)
	}

	// Get updates channel
	updates, _ := bot.UpdatesViaLongPolling(context.Background(), nil)

	// Loop through all updates when they came
	for update := range updates {
		// Process update
	}
}

Telego allows you to choose different JSON encoding/decoding libraries via Go build tags:

• No tags: Uses goccy/go-json (default).
• sonic: Uses bytedance/sonic (high performance, but check platform compatibility).
• stdjson: Uses the standard encoding/json library.

You can also set custom marshal/unmarshal methods globally using SetJSONMarshal and SetJSONUnmarshal.