gotg

package module
v0.0.0-...-84431a8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2026 License: GPL-3.0 Imports: 25 Imported by: 0

README

GoTG

GoTG is a helper package for gotd library, It aims to make td's raw functions easy-to-use with the help of features like using session strings, custom helper functions, storing peers and extracting chat or user ids through it etc.

You can use this package to create bots and userbots with Telegram MTProto easily in golang, for any further help you can check out the documentation or reach us through the following:

  • Support Chat: Chat

Go Reference GPLv3 license

Note: This library is in the beta stage yet and may not be stable for every case.

Installation

You can download the library with the help of the standard go get command.

go get github.com/pageton/gotg

Usage

You can find various examples in the examples' directory, one of them i.e. authorizing as a user is as follows:

package main

import (
	"log"

	"github.com/pageton/gotg"
	"github.com/pageton/gotg/session"
	"github.com/glebarez/sqlite"
)

func main() {
	client, err := gotg.NewClient(
		// Get AppID from https://my.telegram.org/apps
		123456,
		// Get ApiHash from https://my.telegram.org/apps
		"API_HASH_HERE",
		// ClientType, as we defined above
		gotg.ClientTypePhone("PHONE_NUMBER_HERE"),
		// Optional parameters of client
		&gotg.ClientOpts{
			Session: session.SqlSession(sqlite.Open("echobot")),
		},
	)
	if err != nil {
		log.Fatalln("failed to start client:", err)
	}
	client.Idle()
}

Basic Operations

Here are some quick examples on basic operations like sending a message, media etc.

Naming convention:

  • ctx is a *ext.Context object returned as a parameter in all update handlers.
  • update is a *ext.Update object returned as a parameter in all update handlers.
  • chatID is the chat id of the chat you want to send a message to. (type int64)

Note: You do not need to specify the peer field in the request, it is automatically filled by the library.

Sending a Message
ctx.SendMessage(chatID, &tg.MessagesSendMessageRequest{
		Message: "Hello, World!",
		// Peer: ... (No need to setting peer as we have passed chatID)
})
Uploading media on telegram

If you want to send a local file, you will need to upload it to telegram using an uploader instance as we've done below for test.jpg:

f, err := uploader.NewUploader(ctx.Raw).FromPath(ctx, "test.jpg")
if err != nil {
	panic(err)
}
Sending uploaded media to a chat

Let's upload the photo (test.jpg) we just uploaded on telegram:

ctx.SendMedia(chatID, &tg.MessagesSendMediaRequest{
		Message: "This is your caption",
		Media: &tg.InputMediaUploadedPhoto{
			File: f,
		},
})

For media types other than photos, use tg.InputMediaUploadedDocument.

Sending an audio
media := &tg.InputMediaUploadedDocument{
    File:       f,
    MimeType:   "audio/mp4", // or any other mime type like "video/mp4" for videos, "audio/mp4" for audios etc.
    Thumb:      f, // Optional, you can set it to nil if you don't want to set a thumbnail.
    Attributes: []tg.DocumentAttributeClass{&tg.DocumentAttributeFilename{FileName: f.GetName()}},
}

ctx.SendMedia(chatID, &tg.MessagesSendMediaRequest{
		Media:   media,
		Message: "This is your caption"
})
Retrieving a photo from a message and sending it

If you want to send a photo from a message, you can do it like this:

m := update.EffectiveMessage
// we recommend you to check if the media is a photo casting it in real life applications.
photo := m.Media.(*tg.MessageMediaPhoto).Photo.(*tg.Photo)
ctx.SendMedia(chatID, &tg.MessagesSendMediaRequest{
		Media: &tg.InputMediaPhoto{
		// Specifying ID, AccessHash and FileReference of the photo is compulsory.
		ID: &tg.InputPhoto{
			ID:            photo.ID,
			AccessHash:    photo.AccessHash,
			FileReference: photo.FileReference,
		},
	},
})
Sending a file to a chat after retrieving it from a message
m := update.EffectiveMessage
// we recommend you to check if the media is a photo casting it in real life applications.
doc := m.Media.(*tg.MessageMediaDocument).Document.(*tg.Document)
ctx.SendMedia(chatID, &tg.MessagesSendMediaRequest{
		Media: &tg.InputMediaDocument{
		ID: &tg.InputDocument{
			ID:            doc.ID,
			AccessHash:    doc.AccessHash,
			FileReference: doc.FileReference,
		},
	},
})
Working with raw tl functions

Telegram has a big library of functions, Gotg doesn't have helper for all of them currently, but you can use the raw functions to call any function you want and also utilize this library's features. Here is an example of calling the messages.getHistory function to get chat history:

// peer storage is managed by the library automatically with each session. It stores the chat ids and their access hash which are needed to create input peer queries.
peerStorage = ctx.PeerStorage
// get the peer from the chat id
inputPeer := peerStorage.GetInputPeerByID(chatID)
// draw out a raw function call using ctx.Raw api
ctx.Raw.MessagesGetHistory(
	ctx,
	&tg.MessagesGetHistoryRequest{
		// Peer is compulsory
		Peer:  inputPeer,
		Limit: 10,
	},
)

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update the examples as appropriate.

License

GPLv3
Licensed Under GNU General Public License v3

Documentation

Index

Constants

View Source 
const VERSION = "v1.0.0-beta23"

Variables

View Source 
var (
	AuthStatusPhoneAsked        = AuthStatusEvent("phone number asked")
	AuthStatusPhoneRetrial      = AuthStatusEvent("phone number validation retrial")
	AuthStatusPhoneFailed       = AuthStatusEvent("phone number validation failed")
	AuthStatusPhoneCodeAsked    = AuthStatusEvent("phone otp asked")
	AuthStatusPhoneCodeVerified = AuthStatusEvent("phone code verified")
	AuthStatusPhoneCodeRetrial  = AuthStatusEvent("phone code verification retrial")
	AuthStatusPhoneCodeFailed   = AuthStatusEvent("phone code verification failed")
	AuthStatusPasswordAsked     = AuthStatusEvent("2fa password asked")
	AuthStatusPasswordRetrial   = AuthStatusEvent("2fa password verification retrial")
	AuthStatusPasswordFailed    = AuthStatusEvent("2fa password verification failed")
	AuthStatusSuccess           = AuthStatusEvent("authentification success")
)

Functions

func AsBot 

func AsBot(botToken string) clientType

AsBot is a simpler alias for ClientTypeBot

func AsUser 

func AsUser(phoneNumber string) clientType

AsUser is a simpler alias for ClientTypePhone

func ClientTypeBot 

func ClientTypeBot(botToken string) clientType

func ClientTypePhone 

func ClientTypePhone(phoneNumber string) clientType

func SendAuthStatus 

func SendAuthStatus(conversator AuthConversator, event AuthStatusEvent)

func SendAuthStatusWithRetrials 

func SendAuthStatusWithRetrials(conversator AuthConversator, event AuthStatusEvent, attemptsLeft int)

func Simple 

func Simple() clientType

Simple creates a client type for use with string sessions. No phone number or bot token is needed when using this type.

Types

type AuthConversator 

type AuthConversator interface {
	// AskPhoneNumber is called to ask user for phone number.
	// phone number to login should be returned.
	AskPhoneNumber() (string, error)
	// AskCode is called to ask user for OTP.
	// OTP should be returned.
	AskCode() (string, error)
	// AskPassword is called to ask user for 2FA password.
	// 2FA password should be returned.
	AskPassword() (string, error)
	// SendAuthStatus is called to inform the user about
	// the status of the auth process.
	// attemptsLeft is the number of attempts left for the user
	// to enter the input correctly for the current auth status.
	AuthStatus(authStatus AuthStatus)
}

AuthConversator is an interface for asking user for auth information.

func BasicConversator 

func BasicConversator() AuthConversator

type AuthStatus 

type AuthStatus struct {
	Event        AuthStatusEvent
	AttemptsLeft int
}

type AuthStatusEvent 

type AuthStatusEvent string

type Client 

type Client struct {
	// Dispatcher handlers the incoming updates and execute mapped handlers. It is recommended to use dispatcher.MakeDispatcher function for this field.
	Dispatcher          dispatcher.Dispatcher
	ConversationManager *conversation.Manager
	// PublicKeys of telegram.
	//
	// If not provided, embedded public keys will be used.
	PublicKeys []telegram.PublicKey
	// DC ID to connect.
	//
	// If not provided, 2 will be used by default.
	DC int
	// DCList is initial list of addresses to connect.
	DCList dcs.List
	// Resolver to use.
	Resolver dcs.Resolver
	// MigrationTimeout configures migration timeout.
	MigrationTimeout time.Duration
	// AckBatchSize is limit of MTProto ACK buffer size.
	AckBatchSize int
	// AckInterval is maximum time to buffer MTProto ACK.
	AckInterval time.Duration
	// RetryInterval is duration between send retries.
	RetryInterval time.Duration
	// MaxRetries is limit of send retries.
	MaxRetries int
	// ExchangeTimeout is timeout of every key exchange request.
	ExchangeTimeout time.Duration
	// DialTimeout is timeout of creating connection.
	DialTimeout time.Duration
	// CompressThreshold is a threshold in bytes to determine that message
	// is large enough to be compressed using GZIP.
	// If < 0, compression will be disabled.
	// If == 0, default value will be used.
	CompressThreshold int
	// Whether to show the copyright line in console or no.
	DisableCopyright bool
	// Logger is instance of zap.Logger. No logs by default.
	Logger *zap.Logger

	// Self contains details of logged in user in the form of *tg.User.
	Self *tg.User
	// Code for the language used on the device's OS, ISO 639-1 standard.
	SystemLangCode string
	// Code for the language used on the client, ISO 639-1 standard.
	ClientLangCode string
	// PeerStorage is the storage for all the peers.
	// It is recommended to use storage.NewPeerStorage function for this field.
	PeerStorage *storage.PeerStorage
	// NoAutoAuth is a flag to disable automatic authentication
	// if the current session is invalid.
	NoAutoAuth bool
	// NoUpdates is a flag to disable updates.
	NoUpdates bool

	*telegram.Client
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(apiID int, apiHash string, clientType clientType, opts *ClientOpts) (*Client, error)

NewClient creates a new gotg client and logs in to telegram.

func (*Client) CreateContext 

func (c *Client) CreateContext() *adapter.Context

CreateContext creates a new pseudo updates context. A context retrieved from this method should be reused.

func (*Client) ExportStringSession 

func (c *Client) ExportStringSession() (string, error)

ExportStringSession EncodeSessionToString encodes the client session to a string in base64.

Note: You must not share this string with anyone, it contains auth details for your logged in account.

func (*Client) Idle 

func (c *Client) Idle() error

Idle keeps the current goroutined blocked until the client is stopped.

func (*Client) RefreshContext 

func (c *Client) RefreshContext(ctx *adapter.Context)

RefreshContext casts the new context.Context and telegram session to ext.Context (It may be used after doing Stop and Start calls respectively.)

func (*Client) Start 

func (c *Client) Start(opts *ClientOpts) error

Start connects the client to telegram servers and logins. It will return error if the client is already running.

func (*Client) Stop 

func (c *Client) Stop()

Stop cancels the context.Context being used for the client and stops it.

Notes:

1.) Client.Idle() will exit if this method is called.

2.) You can call Client.Start() to start the client again if it was stopped using this method.

type ClientOpts 

type ClientOpts struct {
	// Logger is instance of zap.Logger. No logs by default.
	Logger *zap.Logger
	// Whether to store session and peer storage in memory or not
	//
	// Note: Sessions and Peers won't be persistent if this field is set to true.
	InMemory bool
	// PublicKeys of telegram.
	//
	// If not provided, embedded public keys will be used.
	PublicKeys []telegram.PublicKey
	// DC ID to connect.
	//
	// If not provided, 2 will be used by default.
	DC int
	// DCList is initial list of addresses to connect.
	DCList dcs.List
	// Resolver to use.
	Resolver dcs.Resolver
	// Whether to show the copyright line in console or no.
	DisableCopyright bool
	// Session info of the authenticated user, use session.NewSession function to fill this field.
	Session session.SessionConstructor
	// Setting this field to true will lead to automatically fetch the reply_to_message for a new message update.
	//
	// Set to `false` by default.
	AutoFetchReply bool
	// Setting this field to true will lead to automatically fetch the entire reply_to_message chain for a new message update.
	//
	// Set to `false` by default.
	FetchEntireReplyChain bool
	// Code for the language used on the device's OS, ISO 639-1 standard.
	SystemLangCode string
	// Code for the language used on the client, ISO 639-1 standard.
	ClientLangCode string
	// Custom client device
	Device *telegram.DeviceConfig
	// Panic handles all the panics that occur during handler execution.
	PanicHandler dispatcher.PanicHandler
	// Error handles all the unknown errors which are returned by the handler callback functions.
	ErrorHandler dispatcher.ErrorHandler
	// Custom Middlewares
	Middlewares []telegram.Middleware
	// DispatcherMiddlewares are middleware handlers that run before user-added handlers.
	// These are automatically added to groups 0, 1, 2, ... in order.
	// Useful for i18n, authentication, logging, etc.
	DispatcherMiddlewares []dispatcher.Handler
	// Custom Run() Middleware
	// Can be used for floodWaiter package
	// https://github.com/pageton/gotg/blob/beta/examples/middleware/main.go#L41
	RunMiddleware func(
		origRun func(ctx context.Context, f func(ctx context.Context) error) (err error),
		ctx context.Context,
		f func(ctx context.Context) (err error),
	) (err error)
	// A custom context to use for the client.
	// If not provided, context.Background() will be used.
	// Note: This context will be used for the entire lifecycle of the client.
	Context context.Context
	// AuthConversator is the interface for the authenticator.
	// gotg.BasicConversator is used by default.
	AuthConversator AuthConversator
	// MigrationTimeout configures migration timeout.
	MigrationTimeout time.Duration
	// AckBatchSize is limit of MTProto ACK buffer size.
	AckBatchSize int
	// AckInterval is maximum time to buffer MTProto ACK.
	AckInterval time.Duration
	// RetryInterval is duration between send retries.
	RetryInterval time.Duration
	// MaxRetries is limit of send retries.
	MaxRetries int
	// ExchangeTimeout is timeout of every key exchange request.
	ExchangeTimeout time.Duration
	// DialTimeout is timeout of creating connection.
	DialTimeout time.Duration
	// CompressThreshold is a threshold in bytes to determine that message
	// is large enough to be compressed using GZIP.
	// If < 0, compression will be disabled.
	// If == 0, default value will be used.
	CompressThreshold int
	// NoAutoAuth is a flag to disable automatic authentication
	// if the current session is invalid.
	NoAutoAuth bool
	// NoUpdates is a flag to disable updates.
	NoUpdates bool
	// SendCodeOptions allows overriding AuthSendCode behavior.
	SendCodeOptions *auth.SendCodeOptions
	// Only usable by Users not bots
	// PeersFromDialogs is a flag to enable adding peers fetched
	// from dialogs to memory/database on startup
	PeersFromDialogs bool
	// WaitOnPeersFromDialogs is a flag to enable waiting on
	// PeersFromDialogs to complete during client start
	WaitOnPeersFromDialogs bool
}

type Flow 

type Flow auth.Flow

type KeyboardBuilder 

type KeyboardBuilder struct {
	// contains filtered or unexported fields
}

KeyboardBuilder is a fluent interface for building Telegram keyboards.

func Keyboard 

func Keyboard() *KeyboardBuilder

Keyboard creates a new keyboard builder.

func (*KeyboardBuilder) Build 

func (k *KeyboardBuilder) Build() tg.ReplyMarkupClass

Build builds an inline keyboard (for use with inline buttons).

func (*KeyboardBuilder) BuildReply 

func (k *KeyboardBuilder) BuildReply(opts ...ReplyOptions) tg.ReplyMarkupClass

BuildReply builds a reply keyboard (for regular buttons).

func (*KeyboardBuilder) Button 

func (k *KeyboardBuilder) Button(text, data string) *KeyboardBuilder

Button adds a callback button with data (for inline keyboards).

func (*KeyboardBuilder) Copy 

func (k *KeyboardBuilder) Copy(text, copyText string) *KeyboardBuilder

Copy adds a copy button that copies text to clipboard.

func (*KeyboardBuilder) Next 

func (k *KeyboardBuilder) Next() *KeyboardBuilder

Next moves to the next row.

func (*KeyboardBuilder) RequestGeo 

func (k *KeyboardBuilder) RequestGeo(text string) *KeyboardBuilder

RequestGeo adds a button that requests the user's location.

func (*KeyboardBuilder) RequestPhone 

func (k *KeyboardBuilder) RequestPhone(text string) *KeyboardBuilder

RequestPhone adds a button that requests the user's phone number.

func (*KeyboardBuilder) RequestPoll 

func (k *KeyboardBuilder) RequestPoll(text string, quiz bool) *KeyboardBuilder

RequestPoll adds a button that creates a poll.

func (*KeyboardBuilder) Switch 

func (k *KeyboardBuilder) Switch(text string, samePeer bool, query string) *KeyboardBuilder

Switch adds a switch to inline button. If samePeer is true, the inline query will be sent in the current chat.

func (*KeyboardBuilder) Text 

func (k *KeyboardBuilder) Text(text string) *KeyboardBuilder

Text adds a simple text button (for reply keyboards).

func (*KeyboardBuilder) URL 

func (k *KeyboardBuilder) URL(text, url string) *KeyboardBuilder

URL adds a URL button.

func (*KeyboardBuilder) WebApp 

func (k *KeyboardBuilder) WebApp(text, url string) *KeyboardBuilder

WebApp adds a web app button.

type ReplyOptions 

type ReplyOptions struct {
	Resize      bool
	OneTime     bool
	Selective   bool
	Persistent  bool
	Placeholder string
}

ReplyOptions are options for building reply keyboards.

Source Files

View all Source files

Directories

Path Synopsis
handlers
handlers/filters
middleware
examples
auth-using-api-base command
auth-using-api-base/web
auth-using-string-session/gotg-string command
auth-using-string-session/gramjs-string command
auth-using-string-session/pyrogram-string command
auth-using-string-session/telethon-string command
auth-using-tdata command
authorizing-as-user/memory_session command
authorizing-as-user/sqlite_session command
conversation-bot command
conversation-media command
dispatcher-bot command
downloader command
downloader-v2 command
echo-bot/memory_session command
echo-bot/sqlite_session command
format-example command
i18n-bot command
parser
Package parsemode provides robust parsing for Telegram message formatting.
 Package parsemode provides robust parsing for Telegram message formatting.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.