td

README

td

Telegram client implementation in go.

• Security policy
• User support and dev chat
• Roadmap

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
• Vendored Telegram public keys that are kept up-to-date
• Testing and fuzzing applied to improve durability
• No runtime reflection overhead
• Secure PRNG used for crypto
• 2FA support

Example

You can see cmd/gotdecho for echo bot example.

Auth

User

You can use td/telegram/tgflow package to deal with user auth.

codePrompt := func(ctx context.Context) (string, error) {
	// Safely get authentication code from terminal here,
	// like in https://play.golang.org/p/l-9IP1mrhA
	return code, nil
}
// This will setup and perform authentication flow.
// If account does not require 2FA password, use tgflow.CodeOnlyAuth
// instead of tgflow.ConstantAuth.
if err := tgflow.NewAuth(
	tgflow.ConstantAuth(phone, password, tgflow.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.

client, err := telegram.Dial(ctx, telegram.Options{
    // Grab these from https://my.telegram.org/apps.
    // Never share it or hardcode!
    AppID:   appID,
    AppHash: appHash,
})
if err != 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:

// AccountInstallThemeRequest represents TL type `account.installTheme#7ae43737`.
// Install a theme
//
// See https://core.telegram.org/method/account.installTheme for reference.
type AccountInstallThemeRequest struct {
	// Flags, see TL conditional fields
	Flags bin.Fields
	// Whether to install the dark version
	Dark bool
	// Theme format, a string that identifies the theming engines supported by the client
	//
	// Use SetFormat and GetFormat helpers.
	Format string
	// Theme to install
	//
	// Use SetTheme and GetTheme helpers.
	Theme InputThemeClass
}

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.