Telegram client and MTProto implementation in go.
Before using this library, read How Not To Get Banned guide.
Work in progress. Only go1.16 is supported and no backward compatibility is provided.
Goal of this project is to implement Telegram client while providing building blocks for the other client or even server implementation without performance bottlenecks.
This project is fully non-commercial and not affiliated with any commercial organization (including Telegram LLC).
- Full MTProto 2.0 implementation in go
- Code for Telegram types generated by
./cmd/gotdgen(based on gotd/tl parser) - Embedded official documentation
- Pluggable session storage
- Automatic re-connects with keepalive
- Vendored Telegram public keys that are kept up-to-date
- End-to-end and unit testing, fuzzing
- No runtime reflection overhead
- Secure PRNG used for crypto
- 2FA support
- MTProxy support
- Connection pooling
- Helpers for uploads and downloads
- CDN support
- Automatic DC migration and redirect handling
You can see cmd/gotdecho for simple echo bot example or gotd/bot that can
recover from restarts and fetch missed updates (and also is used as canary for stability testing).
You can use td/telegram/AuthFlow to simplify user authentication flow.
codePrompt := func(ctx context.Context) (string, error) {
// NB: Use "golang.org/x/crypto/ssh/terminal" to prompt password.
fmt.Print("Enter code: ")
code, err := bufio.NewReader(os.Stdin).ReadString('\n')
if err != nil {
return "", err
}
return strings.TrimSpace(code), nil
}
// This will setup and perform authentication flow.
// If account does not require 2FA password, use telegram.CodeOnlyAuth
// instead of telegram.ConstantAuth.
if err := telegram.NewAuth(
telegram.ConstantAuth(phone, password, telegram.CodeAuthenticatorFunc(codePrompt)),
telegram.SendCodeOptions{},
).Run(ctx, client); err != nil {
panic(err)
}Use bot token from @BotFather.
if err := client.AuthBot(ctx, "token:12345"); err != nil {
panic(err)
}You can use generated tg.Client that allows calling any MTProto methods
directly.
// Grab these from https://my.telegram.org/apps.
// Never share it or hardcode!
client := telegram.NewClient(appID, appHash, telegram.Options{})
client.Run(ctx, func(ctx context.Context) error) {
// Grab token from @BotFather.
if err := client.AuthBot(ctx, "token:12345"); err != nil {
return err
}
state, err := tg.NewClient(client).UpdatesGetState(ctx)
if err != nil {
return err
}
// Got state: &{Pts:197 Qts:0 Date:1606855030 Seq:1 UnreadCount:106}
// This will close client and cleanup resources.
return nil
}Code output of gotdgen contains references to TL types, examples, URL to
official documentation and extracted comments from it.
For example, the auth.Authorization type in tg/tl_auth_authorization_gen.go:
// AuthAuthorizationClass represents auth.Authorization generic type.
//
// See https://core.telegram.org/type/auth.Authorization for reference.
//
// Example:
// g, err := DecodeAuthAuthorization(buf)
// if err != nil {
// panic(err)
// }
// switch v := g.(type) {
// case *AuthAuthorization: // auth.authorization#cd050916
// case *AuthAuthorizationSignUpRequired: // auth.authorizationSignUpRequired#44747e9a
// default: panic(v)
// }
type AuthAuthorizationClass interface {
bin.Encoder
bin.Decoder
construct() AuthAuthorizationClass
}Also, the corresponding auth.signIn method:
// AuthSignIn invokes method auth.signIn#bcd51581 returning error if any.
// Signs in a user with a validated phone number.
//
// See https://core.telegram.org/method/auth.signIn for reference.
func (c *Client) AuthSignIn(ctx context.Context, request *AuthSignInRequest) (AuthAuthorizationClass, error) {}The generated constructors contain detailed official documentation, including links:
// FoldersDeleteFolderRequest represents TL type `folders.deleteFolder#1c295881`.
// Delete a peer folder¹
//
// Links:
// 1) https://core.telegram.org/api/folders#peer-folders
//
// See https://core.telegram.org/method/folders.deleteFolder for reference.
type FoldersDeleteFolderRequest struct {
// Peer folder ID, for more info click here¹
//
// Links:
// 1) https://core.telegram.org/api/folders#peer-folders
FolderID int
}Huge thanks to every contributor, dealing with a project of such scale is impossible alone.
Special thanks:
- tdakkota
- Two-factor authentication (SRP)
- Proxy support
- Update dispatcher
- Complete transport support (abridged, padded intermediate and full)
- Telegram server for end-to-end testing
- Multiple major refactorings, including critical cryptographical scope reduction
- Code generation improvements (vector support, multiple modes for pretty-print)
- And many other cool things and performance improvements
- zweihander
- Background pings
- Links in generated documentation
- Message acknowledgements
- Retries
- RPC Engine
The MTProto protocol description is hosted by Telegram.
Most important parts for client implementations:
- Security guidelines for client software developers
Current implementation mostly conforms to security guidelines, but no formal security audit were performed.
- Lonami/grammers (Great Telegram client in Rust, many 60A9 test vectors were used as reference)
- sdidyk/mtproto, cjongseok/mtproto, xelaj/mtproto (MTProto 1.0 in go)
MIT License
Created by Aleksandr (ernado) Razumov
2020