telegram

Documentation

Overview

Package telegram implements Telegram client.

Index

• Constants
• Variables
• type AuthStatus
• type Client
  • func NewClient(appID int, appHash string, opt Options) *Client
  • func (c *Client) AuthBot(ctx context.Context, token string) error
  • func (c *Client) AuthPassword(ctx context.Context, password string) error
  • func (c *Client) AuthSendCode(ctx context.Context, phone string, options SendCodeOptions) (codeHash string, err error)
  • func (c *Client) AuthSignIn(ctx context.Context, phone, code, codeHash string) error
  • func (c *Client) AuthStatus(ctx context.Context) (*AuthStatus, error)
  • func (c *Client) Close(ctx context.Context) error
  • func (c *Client) Connect(ctx context.Context) (err error)
  • func (c *Client) InvokeRaw(ctx context.Context, input bin.Encoder, output bin.Decoder) error
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) RandInt64() (int64, error)
  • func (c *Client) Self(ctx context.Context) (*tg.User, error)
  • func (c *Client) SendMessage(ctx context.Context, req *tg.MessagesSendMessageRequest) error
• type DialFunc
  • func (d DialFunc) DialContext(ctx context.Context, network, address string) (net.Conn, error)
• type Dialer
• type Error
  • func (e Error) Error() string
• type FileSessionStorage
  • func (f *FileSessionStorage) LoadSession(_ context.Context) ([]byte, error)
  • func (f *FileSessionStorage) StoreSession(_ context.Context, data []byte) error
• type Options
• type SendCodeOptions
• type SessionStorage
• type UpdateHandler

Constants

const (
	AddrProduction = "149.154.167.50:443"
	AddrTest       = "149.154.167.40:443"
)

Available MTProto default server addresses.

See https://my.telegram.org/apps.

const (
	TestAppID   = 17349
	TestAppHash = "344583e45741c457fe1862106095a5eb"
)

Test-only credentials. Can be used with AddrTest and tgflow.TestAuth to test authentication.

Reference:

• https://github.com/telegramdesktop/tdesktop/blob/5f665b8ecb48802cd13cfb48ec834b946459274a/docs/api_credentials.md

Variables

var ErrPasswordAuthNeeded = errors.New("2FA required")

ErrPasswordAuthNeeded means that 2FA auth is required.

Call Client.AuthPassword to provide 2FA password.

var ErrSessionNotFound = errors.New("session storage: not found")

ErrSessionNotFound means that session is not found in storage.

Types

type AuthStatus

type AuthStatus struct {
	// Authorized is true if client is authorized.
	Authorized bool
	// User is current User object.
	User *tg.User
}

AuthStatus represents authorization status.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a MTProto client to Telegram.

func NewClient

func NewClient(appID int, appHash string, opt Options) *Client

NewClient creates new unstarted client.

func (*Client) AuthBot

func (c *Client) AuthBot(ctx context.Context, token string) error

AuthBot performs bot authentication request.

func (*Client) AuthPassword

func (c *Client) AuthPassword(ctx context.Context, password string) error

AuthPassword performs login via secure remote password (aka 2FA).

Method can be called after AuthSignIn to provide password if requested.

func (*Client) AuthSendCode

func (c *Client) AuthSendCode(ctx context.Context, phone string, options SendCodeOptions) (codeHash string, err error)

AuthSendCode requests code for provided phone number, returning code hash and error if any. Use tgflow.Auth to reduce boilerplate.

This method should be called first in user authentication flow.

func (*Client) AuthSignIn

func (c *Client) AuthSignIn(ctx context.Context, phone, code, codeHash string) error

AuthSignIn performs sign in with provided user phone, code and code hash.

If ErrPasswordAuthNeeded is returned, call AuthPassword to provide 2FA password.

To obtain codeHash, use AuthSendCode.

func (*Client) AuthStatus

func (c *Client) AuthStatus(ctx context.Context) (*AuthStatus, error)

AuthStatus gets authorization status of client.

func (*Client) Close

func (c *Client) Close(ctx context.Context) error

Close closes underlying connection.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) (err error)

Connect initializes connection to Telegram server and starts internal read loop.

func (*Client) InvokeRaw

func (c *Client) InvokeRaw(ctx context.Context, input bin.Encoder, output bin.Decoder) error

InvokeRaw sens input and decodes result into output.

NOTE: Assuming that call contains content message (seqno increment).

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping sends ping request to server and waits until pong is received or context is canceled.

func (*Client) RandInt64

func (c *Client) RandInt64() (int64, error)

RandInt64 returns new random int64 from random source.

Useful helper for places in API where random int is required.

func (*Client) Self

func (c *Client) Self(ctx context.Context) (*tg.User, error)

Self returns current user.

You can use tg.User.Bot to check whether current user is bot.

func (*Client) SendMessage

func (c *Client) SendMessage(ctx context.Context, req *tg.MessagesSendMessageRequest) error

SendMessage sends message to peer.

type DialFunc

type DialFunc func(ctx context.Context, network, address string) (net.Conn, error)

DialFunc is functional helper for Dialer.

func (DialFunc) DialContext

func (d DialFunc) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext implements Dialer.

type Dialer

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer dials using a context.

type Error

type Error struct {
	Code     int    // 420
	Message  string // FLOOD_WAIT_3
	Type     string // FLOOD_WAIT
	Argument int    // 3
}

Error represents RPC error returned to request.

func (Error) Error

func (e Error) Error() string

type FileSessionStorage

type FileSessionStorage struct {
	Path string
}

FileSessionStorage implements SessionStorage for file system as file stored in Path.

func (*FileSessionStorage) LoadSession

func (f *FileSessionStorage) LoadSession(_ context.Context) ([]byte, error)

LoadSession loads session from file.

func (*FileSessionStorage) StoreSession

func (f *FileSessionStorage) StoreSession(_ context.Context, data []byte) error

StoreSession stores session to file.

type Options

type Options struct {
	// PublicKeys of telegram.
	//
	// If not provided, embedded public keys will be used.
	PublicKeys []*rsa.PublicKey

	// Addr to connect.
	//
	// If not provided, AddrProduction will be used by default.
	Addr string

	// Dialer to use. Default dialer will be used if not provided.
	Dialer Dialer
	// Network to use. Defaults to tcp.
	Network string
	// Random is random source. Defaults to crypto.
	Random io.Reader
	// Logger is instance of zap.Logger. No logs by default.
	Logger *zap.Logger
	// SessionStorage will be used to load and save session data.
	// NB: Very sensitive data, save with care.
	SessionStorage SessionStorage
	// UpdateHandler will be called on received update.
	UpdateHandler UpdateHandler
}

Options of Client.

type SendCodeOptions

type SendCodeOptions struct {
	// AllowFlashCall allows phone verification via phone calls.
	AllowFlashCall bool
	// Pass true if the phone number is used on the current device.
	// Ignored if AllowFlashCall is not set.
	CurrentNumber bool
	// If a token that will be included in eventually sent SMSs is required:
	// required in newer versions of android, to use the android SMS receiver APIs.
	AllowAppHash bool
}

SendCodeOptions defines how to send auth code to user.

type SessionStorage

type SessionStorage interface {
	LoadSession(ctx context.Context) ([]byte, error)
	StoreSession(ctx context.Context, data []byte) error
}

SessionStorage is secure persistent storage for client session.

NB: Implementation security is important, attacker can use not only for connecting as authenticated user or bot, but even decrypting previous messages in some situations.

type UpdateHandler

type UpdateHandler func(ctx context.Context, u *tg.Updates) error

UpdateHandler will be called on received updates from Telegram.