gogram

package module
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2025 License: GPL-3.0 Imports: 32 Imported by: 0

README

Gogram
modern golang library for mtproto
documentation  •  releases  •  telegram chat

GoDoc Go Report Card License GitHub stars GitHub forks

Counter

⭐️ Gogram is a modern, elegant and concurrent MTProto API framework. It enables you to easily interact with the main Telegram API through a user account (custom client) or a bot identity (bot API alternative) using Go.


Gogram is currently in its stable release stage. While there may still be a few bugs, feel free to use it and provide feedback if you encounter any issues or rough edges. 😊

setup

please note that gogram requires Go 1.18 or later to support go-generics

go get -u github.com/Y-Technology/gogram-fork/telegram

quick start

package main

import "github.com/Y-Technology/gogram-fork/telegram"

func main() {
	client, err := telegram.NewClient(telegram.ClientConfig{
		AppID: 6, AppHash: "<app-hash>",
	})

	if err != nil {
		log.Fatal(err)
	}

	client.Conn()

	client.LoginBot("<bot-token>") // or client.Login("<phone-number>") for user account, or client.AuthPrompt() for interactive login

	client.On(telegram.OnMessage, func(message *telegram.NewMessage) error { // client.AddMessageHandler
			message.Reply("Hello from Gogram!")
        		return nil
	}, telegram.FilterPrivate) // waits for private messages only

	client.Idle() // block main goroutine until client is closed
}

support dev

If you'd like to support Gogram, you can consider:

key features

  • ready: 🚀 install gogram with go get and you are ready to go!
  • easy: 😊 makes the telegram api simple and intuitive, while still allowing advanced usages.
  • elegant: 💎 low-level details are abstracted and re-presented in a more convenient way.
  • fast: ⚡ backed by a powerful and concurrent library, gogram can handle even the heaviest workloads.
  • zero dependencies: 🛠️ no need to install anything else than gogram itself.
  • powerful: 💪 full access to telegram's api to execute any official client action and more.
  • feature-rich: 🌟 built-in support for file uploading, formatting, custom keyboards, message editing, moderation tools and more.
  • up-to-date: 🔄 gogram is always in sync with the latest telegram api changes and additions (tl-parser is used to generate the api layer).
Current Layer - 214 (Updated on 2025-09-07)

doing stuff

// sending a message

client.SendMessage("username", "Hello from Gogram!")

client.SendDice("username", "🎲")

client.On("message:/start", func(m *telegram.NewMessage) error {
    m.Reply("Hello from Gogram!") // m.Respond("...")
    return nil
})

// sending media

client.SendMedia("username", "<file-name>", &telegram.MediaOptions{ // filename/inputmedia,...
    Caption: "Hello from Gogram!",
    TTL: int32((math.Pow(2, 31) - 1)), //  TTL For OneTimeMedia
})

client.SendAlbum("username", []string{"<file-name>", "<file-name>"}, &telegram.MediaOptions{ // Array of filenames/inputmedia,...
    Caption: "Hello from Gogram!",
})

// with progress
var pm *telegram.ProgressManager
client.SendMedia("username", "<file-name>", &telegram.MediaOptions{
    Progress: func(a,b int) {
        if pm == nil {
            pm = telegram.NewProgressManager(a, 3) // 3 is edit interval
        }

        if pm.ShouldEdit(b) {
            fmt.Println(pm.GetStats(b)) // client.EditMessage("<chat-id>", "<message-id>", pm.GetStats())
        }
    },
})

// inline queries

client.On("inline:<pattern>", func(iq *telegram.InlineQuery) error { // client.AddInlineHandler
	builder := iq.Builder()
	builder.Article("<title>", "<description>", "<text>", &telegram.ArticleOptions{
			LinkPreview: true,
	})

	return nil
})

// callback queries

client.On("callback:<pattern>", func(cb *telegram.CallbackQuery) error { // client.AddCallbackHandler
    cb.Answer("This is a callback response", &CallbackOptions{
		Alert: true,
	})
    return nil
})

For more examples, check the examples directory.

features

  • basic mtproto implementation (layer 184)
  • updates handling system + cache
  • html, markdown parsing, friendly methods
  • support for flag2.0, layer 147
  • webrtc calls support
  • documentation for all methods
  • stabilize file uploading
  • stabilize file downloading
  • secret chats support
  • cdn dc support
  • reply markup builder helpers
  • reimplement file downloads (more speed + less cpu usage)

known issues

  • ~ file download, is cpu intensive
  • ~ open issues if found :)
  • ~ enhance peer caching.

contributing

Gogram is an open-source project and your contribution is very much appreciated. If you'd like to contribute, simply fork the repository, commit your changes and send a pull request. If you have any questions, feel free to ask.

License

This library is provided under the terms of the GPL-3.0 License.

Force new version

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MessageRequireToAck 

func MessageRequireToAck(msg tl.Object) bool

func RpcErrorToNative 

func RpcErrorToNative(r *objects.RpcError) error

func TryExpandError 

func TryExpandError(errStr string) (nativeErrorName string, additionalData any)

Types

type BadMsgError 

type BadMsgError struct {
	*objects.BadMsgNotification
	Description string
}

func BadMsgErrorFromNative 

func BadMsgErrorFromNative(in *objects.BadMsgNotification) *BadMsgError

func (*BadMsgError) Error 

func (e *BadMsgError) Error() string

type BadSystemMessageCode 

type BadSystemMessageCode int32
const (
	ErrBadMsgUnknown             BadSystemMessageCode = 0
	ErrBadMsgIdTooLow            BadSystemMessageCode = 16
	ErrBadMsgIdTooHigh           BadSystemMessageCode = 17
	ErrBadMsgIncorrectMsgIdBits  BadSystemMessageCode = 18
	ErrBadMsgWrongContainerMsgId BadSystemMessageCode = 19 // this must never happen
	ErrBadMsgMessageTooOld       BadSystemMessageCode = 20
	ErrBadMsgSeqNoTooLow         BadSystemMessageCode = 32
	ErrBadMsgSeqNoTooHigh        BadSystemMessageCode = 33
	ErrBadMsgSeqNoExpectedEven   BadSystemMessageCode = 34
	ErrBadMsgSeqNoExpectedOdd    BadSystemMessageCode = 35
	ErrBadMsgServerSaltIncorrect BadSystemMessageCode = 48
	ErrBadMsgInvalidContainer    BadSystemMessageCode = 64
)

type Config 

type Config struct {
	AuthKeyFile    string
	AuthAESKey     string
	StringSession  string
	SessionStorage session.SessionLoader
	MemorySession  bool
	AppID          int32

	FloodHandler func(err error) bool
	ErrorHandler func(err error)

	ServerHost string
	PublicKey  *rsa.PublicKey
	DataCenter int
	Logger     *utils.Logger
	Proxy      *url.URL
	Mode       string
	Ipv6       bool
	CustomHost bool
	LocalAddr  string
}

type ErrResponseCode 

type ErrResponseCode struct {
	Code           int64
	Message        string
	Description    string
	AdditionalInfo any // some errors has additional data like timeout seconds, dc id etc.
}

func (*ErrResponseCode) Error 

func (e *ErrResponseCode) Error() string

type MTProto 

type MTProto struct {
	Addr string

	DcList *utils.DCOptions

	IpV6 bool

	Logger *utils.Logger
	// contains filtered or unexported fields
}

func NewMTProto 

func NewMTProto(c Config) (*MTProto, error)

func (*MTProto) AddCustomServerRequestHandler 

func (m *MTProto) AddCustomServerRequestHandler(handler func(i any) bool)

func (*MTProto) AppID 

func (m *MTProto) AppID() int32

func (*MTProto) CreateConnection 

func (m *MTProto) CreateConnection(withLog bool) error

func (*MTProto) DeleteSession 

func (m *MTProto) DeleteSession() (err error)

func (*MTProto) Disconnect 

func (m *MTProto) Disconnect() error

func (*MTProto) ExportAuth 

func (m *MTProto) ExportAuth() (*session.Session, int)

func (*MTProto) ExportNewSender 

func (m *MTProto) ExportNewSender(dcID int, mem bool, cdn ...bool) (*MTProto, error)

func (*MTProto) GetAuthKey 

func (m *MTProto) GetAuthKey() []byte

GetAuthKey returns decryption key of current session salt 🧐

func (*MTProto) GetDC 

func (m *MTProto) GetDC() int

func (*MTProto) GetSeqNo 

func (m *MTProto) GetSeqNo() int32

GetSeqNo returns seqno

func (*MTProto) GetServerSalt 

func (m *MTProto) GetServerSalt() int64

GetServerSalt returns current server salt

func (*MTProto) GetSessionID 

func (m *MTProto) GetSessionID() int64

func (*MTProto) HasCdnKey 

func (m *MTProto) HasCdnKey(dc int32) (*rsa.PublicKey, bool)

func (*MTProto) ImportAuth 

func (m *MTProto) ImportAuth(stringSession string) (bool, error)

func (*MTProto) ImportRawAuth 

func (m *MTProto) ImportRawAuth(authKey, authKeyHash []byte, addr string, appID int32) (bool, error)

func (*MTProto) InvokeRequestWithoutUpdate 

func (m *MTProto) InvokeRequestWithoutUpdate(data tl.Object, expectedTypes ...reflect.Type) error

func (*MTProto) IsTcpActive 

func (m *MTProto) IsTcpActive() bool

func (*MTProto) LoadSession 

func (m *MTProto) LoadSession(sess *session.Session) error

func (*MTProto) MakeRequest 

func (m *MTProto) MakeRequest(msg tl.Object) (any, error)

func (*MTProto) MakeRequestCtx 

func (m *MTProto) MakeRequestCtx(ctx context.Context, msg tl.Object) (any, error)

func (*MTProto) MakeRequestWithHintToDecoder 

func (m *MTProto) MakeRequestWithHintToDecoder(msg tl.Object, expectedTypes ...reflect.Type) (any, error)

func (*MTProto) Ping 

func (m *MTProto) Ping() time.Duration

func (*MTProto) Reconnect 

func (m *MTProto) Reconnect(WithLogs bool) error

func (*MTProto) SaveSession 

func (m *MTProto) SaveSession(mem bool) (err error)

func (*MTProto) SetAppID 

func (m *MTProto) SetAppID(appID int32)

func (*MTProto) SetAuthKey 

func (m *MTProto) SetAuthKey(key []byte)

func (*MTProto) SetCdnKeys 

func (m *MTProto) SetCdnKeys(keys map[int32]*rsa.PublicKey)

func (*MTProto) SetTerminated 

func (m *MTProto) SetTerminated(val bool)

func (*MTProto) SwitchDc 

func (m *MTProto) SwitchDc(dc int) (*MTProto, error)

func (*MTProto) TcpState 

func (m *MTProto) TcpState() *TcpState

func (*MTProto) Terminate 

func (m *MTProto) Terminate() error

func (*MTProto) UpdateSeqNo 

func (m *MTProto) UpdateSeqNo() int32

type TcpState 

type TcpState struct {
	Active atomic.Bool
	Cond   *sync.Cond
}

func NewTcpState 

func NewTcpState() *TcpState

func (*TcpState) SetActive 

func (m *TcpState) SetActive(active bool)

func (*TcpState) WaitForActive 

func (m *TcpState) WaitForActive()

Source Files

View all Source files

Directories

Path Synopsis
examples
auth
bot
broadcast
buttons
cache
conversation
fileid
getchats
gifts
inline
multiple
progress
proxy command
react
sessions/pyrogram
sessions/string
sessions/tdata
sessions/telethon
simple command
stars
internal
aes_ige
encoding/tl
keys
math
mode
mtproto/messages
mtproto/objects
session
transport
utils

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.