td

README

td

Telegram client implementation in go.

• Security policy
• User support and dev chat
• Roadmap
• Contributing

Before using this library, read How Not To Get Banned guide.

Status

Work in progress. Only go1.15 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).

Features

• 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

Example

You can see cmd/gotdecho for echo bot example.

Auth

User

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)
}

Bot

Use bot token from @BotFather.

if err := client.AuthBot(ctx, "token:12345"); err != nil {
    panic(err)
}

Calling MTProto directly

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{})
if err := client.Connect(ctx); != nil {
    panic(err)
}
// Grab token from @BotFather.
if err := client.AuthBot(ctx, "token:12345"); err != nil {
    panic(err)
}
// updates.getState#edd4882a
state, err := tg.NewClient(client).UpdatesGetState(ctx, &tg.UpdatesGetStateRequest{})
if err != nil {
    panic(err)
}
// Got state: &{Pts:197 Qts:0 Date:1606855030 Seq:1 UnreadCount:106}

Generated code

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
}

Contributions

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

Reference

The MTProto protocol description is hosted by Telegram.

Most important parts for client impelemtations:

• Security guidelines for client software developers

Current implementation does not conform to security guidelines and should be used only as reference or for testing.

Prior art

• Lonami/grammers (Great Telegram client in Rust, many test vectors were used as reference)
• sdidyk/mtproto, cjongseok/mtproto, xelaj/mtproto (MTProto 1.0 in go)

License

MIT License

Created by Aleksandr (ernado) Razumov

2020

Documentation

Overview

Package td implements MTProto encoding and decoding.