Client

ClientConfig reference

Every field on ClientConfig, what it controls, and when you would touch it. The fields are grouped by what they do; the order here is not the order in the struct.

A maximally-configured client

client, _ := telegram.NewClient(telegram.ClientConfig{
	// Identity
	AppID:           12345,
	AppHash:         "abcdef...",
	DeviceConfig:    telegram.DeviceConfig{
		DeviceModel:    "MyService v1",
		SystemVersion:  "linux",
		AppVersion:     "1.0.0",
		LangCode:       "en",
		SystemLangCode: "en",
	},

	// Session
	Session:        "bot.session",
	SessionAESKey:  os.Getenv("SESSION_KEY"),
	MemorySession:  false,

	// Transport
	DataCenter:      4,
	UseWebSocket:    false,
	UseWebSocketTLS: false,
	TestMode:        false,
	ForceIPv6:       false,
	Proxy:           nil,

	// Behaviour
	ParseMode:       "Markdown",
	DisableCache:    false,
	NoUpdates:       false,
	NoPreconnect:    false,
	DisableGapFetch: false,
	CacheSenders:    true,

	// Limits & retries
	Timeout:          60,
	ReqTimeout:       60,
	SleepThresholdMs: 60000,
	AlbumWaitTime:    200,

	// Logging
	LogLevel: telegram.LogInfo,
})

client, _ := telegram.NewClient(telegram.ClientConfig{
	// Identity
	AppID:           12345,
	AppHash:         "abcdef...",
	DeviceConfig:    telegram.DeviceConfig{
		DeviceModel:    "MyService v1",
		SystemVersion:  "linux",
		AppVersion:     "1.0.0",
		LangCode:       "en",
		SystemLangCode: "en",
	},

	// Session
	Session:        "bot.session",
	SessionAESKey:  os.Getenv("SESSION_KEY"),
	MemorySession:  false,

	// Transport
	DataCenter:      4,
	UseWebSocket:    false,
	UseWebSocketTLS: false,
	TestMode:        false,
	ForceIPv6:       false,
	Proxy:           nil,

	// Behaviour
	ParseMode:       "Markdown",
	DisableCache:    false,
	NoUpdates:       false,
	NoPreconnect:    false,
	DisableGapFetch: false,
	CacheSenders:    true,

	// Limits & retries
	Timeout:          60,
	ReqTimeout:       60,
	SleepThresholdMs: 60000,
	AlbumWaitTime:    200,

	// Logging
	LogLevel: telegram.LogInfo,
})

Identity

AppIDrequired

int32

Your application id from my.telegram.org. A plain integer.

AppHashrequired

string

Your application hash. 32 hex characters.

DeviceConfig

The strings reported to Telegram during initConnection. Telegram shows DeviceModel, SystemVersion, and AppVersionin the user's active sessions list. Defaults are sensible — override when you want your service to stand out.

Session

Session string: Path to a file where the auth key is persisted. Created on first login, read on subsequent runs.
StringSession string: An exported base64 session string, used instead of (or in addition to) a file. Useful when you cannot write to disk — serverless, ephemeral containers, kubernetes secrets.
SessionName string: Identifier used in log prefixes so multi-session servers stay readable.
SessionAESKey string: An AES-256 key (32 raw bytes or 64 hex chars). When set, the session file is encrypted with it. Lose the key, lose the session.
MemorySession bool: Do not touch disk. The auth key lives in memory and is gone when the process exits. Good for short-lived workers, tests, and the tools.

Transport

DataCenter int: Which DC to dial initially. Defaults to 4. The library re-routes automatically if your account/bot lives elsewhere, so the only reason to set this is to skip the migration round-trip on first connect.
IpAddr string: Override the DC IP. Use only if you need to point at a specific endpoint (custom MTProxy, test rig).
UseWebSocket bool · UseWebSocketTLS bool: Switch transport from raw TCP to WebSocket / WSS. Required when running inside js/wasm (the browser has no raw TCP). Slightly more overhead per request than TCP.
TestMode bool: Connect to Telegram's test backend instead of production. You need a separate test-environment account.
ForceIPv6 bool: Prefer the IPv6 addresses in the DC list. Off by default.
Proxy Proxy: SOCKS5, HTTP, or MTProxy. See Proxies.
LocalAddr string: Bind outbound connections to a specific local interface (ip:port). Useful on multi-homed hosts.
TransportMode string: Wire framing. Abridged (default) is most compact; Intermediate, Full, and PaddedIntermediate exist for compat with intermediaries.

Behaviour

ParseMode string: Default parse mode for outgoing messages. "Markdown" or "HTML". Per-message overrides via SendOptions.
NoUpdates bool: Disable the update dispatcher. The client will not receive incoming messages or events. Use this for one-shot CLI tools that just send something and exit.
DisableCache bool: Skip the in-memory peer/chat cache. Every peer resolution hits the network. Off by default; turn on only when you have a custom storage backend that is faster.
Cache *CACHE: Provide your own cache implementation. See Custom peer storage.
CacheSenders bool: Keep the per-DC exported senders alive between file operations. Massive speedup for repeated downloads/uploads against the same DC.
NoPreconnect bool: Skip the auto-connect inside NewClient. Useful when you want to inspect/modify config before opening the wire.
DisableGapFetch bool: Stop the dispatcher from auto-filling channel/account update gaps. The client will only ask for differences on the explicit UpdatesTooLong / ChannelTooLong service messages. Lower bandwidth, but you may miss intermediate state.
CommandPrefixes string: Characters that mark a bot command. Default "/!".
AlbumWaitTime int64: Milliseconds to wait for the rest of a media album to arrive before firing the message handler with the partial set. Default 200ms.
EnablePFS bool: Perfect Forward Secrecy. Rotate temporary auth keys every hour. On by default in newer versions of gogram.

Limits & retries

Timeout int: TCP connect timeout in seconds.
ReqTimeout int: Per-RPC timeout in seconds.
SleepThresholdMs int: How long to silently sleep on a FLOOD_WAIT before bubbling the error to your code. Below this, the client waits and retries automatically; above it, your code gets the error and decides.
FloodHandler func(error) bool: Called on every FLOOD_WAIT. Return true to let the client retry after sleeping.
ErrorHandler func(error) bool: Called on every RPC error. Return true to retry, false to surface.
MaxReconnectAttempts / MaxReconnectDelay / BaseReconnectDelay: Backoff knobs for the auto-reconnect loop. The defaults handle weeks of network flakiness without intervention.

Logging

LogLevel LogLevel: One of LogTrace, LogDebug, LogInfo, LogWarn, LogError. Default LogInfo.
Logger Logger: Plug in your own logger. The interface is small — Debug, Info, Warn, Error with structured fields. See Logging & debugging.

Advanced

PublicKeys []*rsa.PublicKey: Override Telegram's RSA keys used for the initial handshake. You almost never need this; the defaults ship in the library and rotate on releases.
OnMigration func(): Callback fired after a DC migration completes. Use it to log or invalidate per-DC caches.

Client

Setting up the client

Client

Transport & DCs