Documentation
¶
Overview ¶
Package telegram implements Telegram client.
Index ¶
- Constants
- Variables
- func BotFromEnvironment(ctx context.Context, opts Options, ...) error
- func RunUntilCanceled(ctx context.Context, client *Client) error
- func TestClient(ctx context.Context, opts Options, ...) error
- type Client
- func (c *Client) API() *tg.Client
- func (c *Client) Auth() *auth.Client
- func (c *Client) Config() tg.Config
- func (c *Client) DC(ctx context.Context, dc int, max int64) (CloseInvoker, error)
- func (c *Client) Invoke(ctx context.Context, input bin.Encoder, output bin.Decoder) error
- func (c *Client) MediaOnly(ctx context.Context, dc int, max int64) (CloseInvoker, error)
- func (c *Client) Pool(max int64) (CloseInvoker, error)
- func (c *Client) RandInt64() (int64, error)
- func (c *Client) Run(ctx context.Context, f func(ctx context.Context) error) (err error)
- func (c *Client) Self(ctx context.Context) (*tg.User, error)
- func (c *Client) SendMessage(ctx context.Context, req *tg.MessagesSendMessageRequest) errordeprecated
- type CloseInvoker
- type DeviceConfig
- type Error
- type FileSessionStorage
- type InvokeFunc
- type Middleware
- type MiddlewareFunc
- type Options
- type SessionStorage
- type UpdateHandler
- type UpdateHandlerFunc
Examples ¶
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 TestAuth to test authentication.
Reference:
const ErrFloodWait = tgerr.ErrFloodWait
ErrFloodWait is error type of "FLOOD_WAIT" error.
const Port = 443
Port is default port used by telegram.
Variables ¶
var AsFloodWait = tgerr.AsFloodWait // nolint:gochecknoglobals
AsFloodWait returns wait duration and true boolean if err is the "FLOOD_WAIT" error.
Client should wait for that duration before issuing new requests with same method.
Functions ¶
func BotFromEnvironment ¶ added in v0.19.0
func BotFromEnvironment( ctx context.Context, opts Options, setup func(ctx context.Context, client *Client) error, cb func(ctx context.Context, client *Client) error, ) error
BotFromEnvironment creates bot client using ClientFromEnvironment connects to server and authenticates it.
Variables: BOT_TOKEN — token from BotFather.
func RunUntilCanceled ¶ added in v0.26.0
RunUntilCanceled is client callback which locks until client context is canceled.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a MTProto client to Telegram.
Example (Mtproxy) ¶
package main import ( "context" "encoding/hex" "fmt" "os" "os/signal" "golang.org/x/xerrors" "github.com/gotd/td/telegram" "github.com/gotd/td/telegram/dcs" "github.com/gotd/td/tg" ) func connectViaMTProxy(ctx context.Context) error { secret, err := hex.DecodeString(os.Getenv("SECRET")) if err != nil { return xerrors.Errorf("parse secret: %w", err) } resolver, err := dcs.MTProxy( os.Getenv("PROXY_ADDR"), secret, dcs.MTProxyOptions{}, ) if err != nil { return xerrors.Errorf("create MTProxy resolver: %w", err) } client, err := telegram.ClientFromEnvironment(telegram.Options{ Resolver: resolver, }) if err != nil { return xerrors.Errorf("create client: %w", err) } return client.Run(ctx, func(ctx context.Context) error { cfg, err := tg.NewClient(client).HelpGetConfig(ctx) if err != nil { return xerrors.Errorf("get config: %w", err) } fmt.Println("This DC: ", cfg.ThisDC) return nil }) } func main() { ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt) defer cancel() if err := connectViaMTProxy(ctx); err != nil { _, _ = fmt.Fprintf(os.Stderr, "%+v\n", err) os.Exit(1) } }
Output:
func ClientFromEnvironment ¶ added in v0.19.0
ClientFromEnvironment creates client using OptionsFromEnvironment but does not connect to server.
Variables:
APP_ID: app_id of Telegram app. APP_HASH: app_hash of Telegram app.
func (*Client) Auth ¶ added in v0.43.0
Auth returns auth client.
Example ¶
package main import ( "bufio" "context" "fmt" "log" "os" "strconv" "strings" "github.com/gotd/td/telegram" "github.com/gotd/td/telegram/auth" "github.com/gotd/td/tg" ) func main() { check := func(err error) { if err != nil { panic(err) } } var ( appIDString = os.Getenv("APP_ID") appHash = os.Getenv("APP_HASH") phone = os.Getenv("PHONE") pass = os.Getenv("PASSWORD") ) if appIDString == "" || appHash == "" || phone == "" || pass == "" { log.Fatal("PHONE, PASSWORD, APP_ID or APP_HASH is not set") } appID, err := strconv.Atoi(appIDString) check(err) ctx := context.Background() client := telegram.NewClient(appID, appHash, telegram.Options{}) codeAsk := func(ctx context.Context, sentCode *tg.AuthSentCode) (string, error) { fmt.Print("code:") code, err := bufio.NewReader(os.Stdin).ReadString('\n') if err != nil { return "", err } code = strings.ReplaceAll(code, "\n", "") return code, nil } check(client.Run(ctx, func(ctx context.Context) error { return auth.NewFlow( auth.Constant(phone, pass, auth.CodeAuthenticatorFunc(codeAsk)), auth.SendCodeOptions{}, ).Run(ctx, client.Auth()) })) }
Output:
Example (Test) ¶
package main import ( "context" "crypto/rand" "github.com/gotd/td/telegram" "github.com/gotd/td/telegram/auth" "github.com/gotd/td/telegram/dcs" ) func main() { // Example of using test server. const dcID = 2 ctx := context.Background() client := telegram.NewClient(telegram.TestAppID, telegram.TestAppHash, telegram.Options{ DC: dcID, DCList: dcs.Staging(), }) if err := client.Run(ctx, func(ctx context.Context) error { return auth.NewFlow( auth.Test(rand.Reader, dcID), auth.SendCodeOptions{}, ).Run(ctx, client.Auth()) }); err != nil { panic(err) } }
Output:
func (*Client) Invoke ¶ added in v0.43.0
Invoke invokes raw MTProto RPC method. It sends input and decodes result into output.
func (*Client) MediaOnly ¶ added in v0.30.0
MediaOnly creates new multi-connection invoker to given DC ID. It connects to MediaOnly DCs.
func (*Client) Pool ¶ added in v0.22.0
func (c *Client) Pool(max int64) (CloseInvoker, error)
Pool creates new multi-connection invoker to current DC.
func (*Client) RandInt64 ¶
RandInt64 returns new random int64 from random source.
Useful helper for places in API where random int is required.
func (*Client) Run ¶ added in v0.18.0
Run starts client session and blocks until connection close. The f callback is called on successful session initialization and Run will return on f() result.
Context of callback will be canceled if fatal error is detected. The ctx is used for background operations like updates handling or pools.
See `examples/bg-run` and `contrib/gb` package for classic approach without explicit callback, with Connect and defer close().
func (*Client) Self ¶ added in v0.11.0
Self returns current user.
You can use tg.User.Bot to check whether current user is bot.
func (*Client) SendMessage
deprecated
type CloseInvoker ¶ added in v0.26.0
CloseInvoker is a closeable tg.Invoker.
type DeviceConfig ¶ added in v0.21.0
type DeviceConfig = manager.DeviceConfig
DeviceConfig is config which send when Telegram connection session created.
type FileSessionStorage ¶
type FileSessionStorage = session.FileStorage
FileSessionStorage is alias of mtproto.FileSessionStorage.
type InvokeFunc ¶ added in v0.43.0
InvokeFunc implements tg.Invoker as function.
type Middleware ¶ added in v0.43.0
type Middleware interface {
Handle(next tg.Invoker) InvokeFunc
}
Middleware returns new InvokeFunc for next invoker.
Example ¶
invoker := InvokeFunc(func(ctx context.Context, input bin.Encoder, output bin.Decoder) error { fmt.Println("invoke") return nil }) printMiddleware := func(message string) Middleware { return MiddlewareFunc(func(next tg.Invoker) InvokeFunc { return func(ctx context.Context, input bin.Encoder, output bin.Decoder) error { fmt.Println(message, "(start)") err := next.Invoke(ctx, input, output) fmt.Println(message, "(end)") return err } }) } // Testing composed invoker. _ = chainMiddlewares(invoker, printMiddleware("first"), printMiddleware("second"), ).Invoke(context.Background(), nil, nil)
Output: first (start) second (start) invoke second (end) first (end)
type MiddlewareFunc ¶ added in v0.43.0
type MiddlewareFunc func(next tg.Invoker) InvokeFunc
MiddlewareFunc implements Middleware as function.
func (MiddlewareFunc) Handle ¶ added in v0.43.0
func (m MiddlewareFunc) Handle(next tg.Invoker) InvokeFunc
Handle implements Middleware.
type Options ¶
type Options struct { // PublicKeys of telegram. // // If not provided, embedded public keys will be used. PublicKeys []*rsa.PublicKey // DC ID to connect. // // If not provided, 2 will be used by default. DC int // DCList is initial list of addresses to connect. DCList dcs.List // Resolver to use. Resolver dcs.Resolver // NoUpdates enables no updates mode. // // Enabled by default if no UpdateHandler is provided. NoUpdates bool // ReconnectionBackoff configures and returns reconnection backoff object. ReconnectionBackoff func() backoff.BackOff // MigrationTimeout configures migration timeout. MigrationTimeout time.Duration // 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 // Middlewares list allows to wrap tg.Invoker. Can be useful for metrics, // tracing, etc. Note that order is important, see ExampleMiddleware. // // Middlewares are called in order from first to last. Middlewares []Middleware // AckBatchSize is maximum ack-s to buffer. AckBatchSize int // AckInterval is maximum time to buffer ack. AckInterval time.Duration RetryInterval time.Duration MaxRetries int // ReadConcurrency is a count of workers to decrypt and decode incoming messages. // Should be more than 2 to make effect. Otherwise ignored. ReadConcurrency int // NoBufferReuse disables buffer reuse for workers that decrypt and decode // incoming messages. Each worker adds around 0.5 MiB to the total used // memory. The default behavior is to keep the buffer for reuse, but in // programs that maintain many connections this quickly adds up to hundreds // of megabytes (buffer size multiplied by the number of connections and read // concurrency). NoBufferReuse bool // Device is device config. // Will be sent with session creation request. Device DeviceConfig MessageID mtproto.MessageIDSource Clock clock.Clock }
Options of Client.
func OptionsFromEnvironment ¶ added in v0.19.0
OptionsFromEnvironment fills unfilled field in opts parameter using environment variables.
Variables:
SESSION_FILE: path to session file SESSION_DIR: path to session directory, if SESSION_FILE is not set ALL_PROXY, NO_PROXY: see https://pkg.go.dev/golang.org/x/net/proxy#FromEnvironment
type SessionStorage ¶
SessionStorage is alias of mtproto.SessionStorage.
type UpdateHandler ¶
type UpdateHandler interface {
Handle(ctx context.Context, u tg.UpdatesClass) error
}
UpdateHandler will be called on received updates from Telegram.
type UpdateHandlerFunc ¶ added in v0.39.0
type UpdateHandlerFunc func(ctx context.Context, u tg.UpdatesClass) error
UpdateHandlerFunc type is an adapter to allow the use of ordinary function as update handler.
UpdateHandlerFunc(f) is an UpdateHandler that calls f.
func (UpdateHandlerFunc) Handle ¶ added in v0.39.0
func (f UpdateHandlerFunc) Handle(ctx context.Context, u tg.UpdatesClass) error
Handle calls f(ctx, u)
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
Package auth provides authentication on top of tg.Client.
|
Package auth provides authentication on top of tg.Client. |
Package dcs contains Telegram DCs list and some helpers.
|
Package dcs contains Telegram DCs list and some helpers. |
Package downloader contains downloading files helpers.
|
Package downloader contains downloading files helpers. |
internal
|
|
e2etest
Package e2etest contains some helpers to make external E2E tests using Telegram staging server.
|
Package e2etest contains some helpers to make external E2E tests using Telegram staging server. |
manager
Package manager contains connection management utilities.
|
Package manager contains connection management utilities. |
upconv
Package upconv contains updates conversion helpers.
|
Package upconv contains updates conversion helpers. |
Package message contains some useful utilities for creating Telegram messages.
|
Package message contains some useful utilities for creating Telegram messages. |
entity
Package entity contains message formatting and styling helpers.
|
Package entity contains message formatting and styling helpers. |
html
Package html contains HTML styling options.
|
Package html contains HTML styling options. |
inline
Package inline contains inline query results builder.
|
Package inline contains inline query results builder. |
internal/deeplink
Package deeplink contains deeplink parsing helpers.
|
Package deeplink contains deeplink parsing helpers. |
markup
Package markup contain bots inline markup builder.
|
Package markup contain bots inline markup builder. |
peer
Package peer conatains some peer resolving and extracting helpers.
|
Package peer conatains some peer resolving and extracting helpers. |
styling
Package styling contains styling options for Telegram messages.
|
Package styling contains styling options for Telegram messages. |
unpack
Package unpack contains some updates result unpacking helpers.
|
Package unpack contains some updates result unpacking helpers. |
Package query contains generic pagination helpers.
|
Package query contains generic pagination helpers. |
cached
Package cached contains cached query helpers.
|
Package cached contains cached query helpers. |
channels/participants
Package participants contains channel participants iteration helper.
|
Package participants contains channel participants iteration helper. |
contacts/blocked
Package blocked contains blocked contacts iteration helper.
|
Package blocked contains blocked contacts iteration helper. |
dialogs
Package dialogs contains dialog iteration helper.
|
Package dialogs contains dialog iteration helper. |
hasher
Package hasher contains Telegram pagination hash implementation.
|
Package hasher contains Telegram pagination hash implementation. |
internal/genutil
Package genutil is a utility package for query helpers codegeneration.
|
Package genutil is a utility package for query helpers codegeneration. |
messages
Package messages contains message iteration helper.
|
Package messages contains message iteration helper. |
messages/stickers/featured
Package featured contains featured stickers iteration helper.
|
Package featured contains featured stickers iteration helper. |
photos
Package photos contains photos iteration helper.
|
Package photos contains photos iteration helper. |
Package thumbnail implements expanding of stripped telegram thumbnails.
|
Package thumbnail implements expanding of stripped telegram thumbnails. |
Package updates provides a Telegram's state synchronization engine.
|
Package updates provides a Telegram's state synchronization engine. |
internal/e2e
Package e2e contains updates.Engine tests.
|
Package e2e contains updates.Engine tests. |
Package uploader contains uploading files helpers.
|
Package uploader contains uploading files helpers. |
source
Package source contains remote source interface and implementations for uploader.
|
Package source contains remote source interface and implementations for uploader. |