Introduction

What is gogram

gogram is a pure-Go implementation of Telegram's MTProto 2.0 protocol with a high-level client wrapped around it. It generates Go types for every constructor and method in the TL schema (layer 227 at the time of writing), handles the encryption, DC routing, and session management for you, and exposes a friendly surface so that the common things are easy.

It is the library you reach for when the HTTP Bot API runs out of features — when you want to log in as a user, work with files larger than 50 MB, listen to raw updates, run a userbot, mirror channels, or anything else that requires speaking the protocol directly.

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:   12345,
	AppHash: "abcdef0123456789abcdef0123456789",
	Session: "bot.dat",
})
client.Connect()
client.LoginBot("123:abc")

client.On("/start", func(m *telegram.NewMessage) error {
	_, err := m.Reply("hi")
	return err
})

client.Idle()

client, _ := telegram.NewClient(telegram.ClientConfig{
	AppID:   12345,
	AppHash: "abcdef0123456789abcdef0123456789",
	Session: "bot.dat",
})
client.Connect()
client.LoginBot("123:abc")

client.On("/start", func(m *telegram.NewMessage) error {
	_, err := m.Reply("hi")
	return err
})

client.Idle()

What it is not

gogram is not a Bot API wrapper. It does not call api.telegram.org. Bot tokens log in over MTProto exactly like user accounts do, and the same client object handles both. If you only need to send messages from a bot and the Bot API covers it, that is fine — use the Bot API. gogram is for when it does not.

The shape of the library

The library splits into a few layers:

github.com/amarnathcjd/gogram

The MTProto core: encryption, transport, session storage, RPC, reconnection, DC migration. You rarely touch this directly.

github.com/amarnathcjd/gogram/telegram

The high-level client. This is where you live 99 % of the time: NewClient,SendMessage, On, the dispatcher, conversation helpers, file upload/download.

Generated TL types

Every constructor and method from the schema, generated into Go structs and methods on theClient. You can always drop down to these when a helper does not exist for what you want.

Design choices

A few decisions you will run into early:

• One client, two roles. Bots and user accounts use the sameClient. LoginBot(token) for bots,Login(phone) for users.
• Peer IDs accept anything. Most methods take peerID any— you can pass an int64 id, a username string with or without @, a phone number, a t.me link, or a resolved InputPeer. The library figures it out and caches the result.
• Get vs Iter. Listy methods come in two flavours. Get* returns a single batch; Iter* is a generator that pages for you. Pick by whether you want a quick answer or a stream.
• Sessions are portable. Auth keys can be written to a file, exported to a base64 string for moving between hosts, kept in memory only, or encrypted at rest with an AES key.
• Reconnects are automatic.Dropped TCP, DC migration, flood waits, network flips — the client handles them under the hood unless you turn that off.

Where to go next

If you are new, follow the next two pages in order: Installation covers picking a Go version and adding the module. Your first bot walks through an echo bot you can actually run. After that, the sidebar is organised roughly in the order you will need things.