Client Settings¶

Client takes a lot of arguments. Most have a default you never need to touch; the ones on this page are the ones worth knowing about, grouped by what they change.

The full list with types and descriptions is in the Client reference.

How your client appears¶

Telegram shows every logged-in client in Settings → Devices → Active Sessions. By default yours reads:

Device Model: CPython x.y.z
Application: Pyrogram x.y.z, where x.y.z is the wzgram version
System Version: the platform wzgram detects

Change any of it:

app = Client(
    "my_account",
    app_version="MyApp 1.2.3",
    device_model="PC",
    system_version="Linux",
)

client_platform (ClientPlatform) is a separate, structured hint Telegram uses for feature availability — set it to what your program actually is rather than leaving it OTHER if it matters to you.

Language¶

lang_code tells Telegram which language to speak in terms of service, bot replies and service messages. It takes an ISO 639-1 code and defaults to "en":

app = Client("my_account", lang_code="it")

system_lang_code and lang_pack exist for completeness and rarely need changing.

Where the session lives¶

Argument	Default	What it does
`name`	—	session name; becomes `<name>.session` on disk
`workdir`	the parent dir	where that file is written
`in_memory`	`None`	keep the session in memory only, discarded on stop
`session_string`	`None`	resume from an exported string instead of a file
`storage_engine`	`None`	another engine: MongoDB, Redis, hybrid, or your own

See Storage Engines for the remote and hybrid engines, and Session Strings for moving a session as text.

An explicit storage_engine wins over session_string: the string is loaded into that engine rather than replacing it.

Logging in without prompts¶

Supplying these makes the first login non-interactive, which is what you want in a container where nobody is at a terminal:

Argument	What it does
`bot_token`	log in as a bot
`phone_number`	the number to authorize, instead of asking
`phone_code`	the login code, if you have a way to obtain it
`password`	the two-step verification password
`hide_password`	read the password without echoing it

Note

A prompt on a host with no terminal fails rather than retrying. That is deliberate: the retry loop it replaced spun thousands of times a second against an EOF.

Updates¶

Argument	Default	What it does
`workers`	cpu + 4	dispatcher worker tasks running your handlers
`no_updates`	`False`	receive no updates at all — for batch programs
`skip_updates`	`True`	drop updates that arrived while you were offline
`auto_no_updates`	`True`	wrap read-only calls so they do not generate update traffic
`fetch_replies`	`True`	resolve the message a reply points at
`fetch_topics`	`True`	resolve the forum topic a message belongs to
`fetch_stories`	`True`	resolve stories referenced by a message
`fetch_stickers`	`True`	resolve sticker sets

The four fetch_* switches each cost an extra lookup per update. Turning off the ones you never read is the cheapest throughput win available on a busy client.

Rate limiting and floods¶

Argument	Default	What it does
`sleep_threshold`	`10`	seconds of `FloodWait` wzgram waits out for you
`rate_limits`	`None`	override the client-side token buckets

app = Client(
    "my_bot",
    sleep_threshold=60,
    rate_limits={"media": {"rate": 2, "burst": 4}},
)

A FloodWait longer than sleep_threshold is raised for you to handle. See Rate Limiting.

Transfers and caches¶

Argument	Default	What it does
`max_concurrent_transmissions`	`16`	uploads and downloads running at once
`max_message_cache_size`	`1000`	messages held in memory
`max_topic_cache_size`	`1000`	forum topics held in memory

Memory budgets that are process-wide rather than per client — read-ahead, in-flight media, the peer cache — are environment variables instead, and are listed in Performance and Resource Budgets.

Conversations¶

Argument	Default	What it does
`max_listeners`	process-wide 1000	outstanding `listen()` waiters
`listener_timeout`	`300`	default seconds before a waiter gives up
`unallowed_click_alert`	`True`	answer button presses from the wrong user with an alert
`unallowed_click_alert_text`	—	what that alert says

See Listeners.

Network¶

Argument	Default	What it does
`ipv6`	`False`	connect over IPv6
`proxy`	`None`	SOCKS4/5 or HTTP proxy — see Proxy Settings
`test_mode`	`False`	use Telegram’s test datacenters — see Test Servers
`protocol_factory`	abridged	the MTProto transport to use
`connection_factory`	`Connection`	a custom connection implementation
`init_connection_params`	`None`	extra fields for `InitConnection`

Text and plugins¶

Argument	Default	What it does
`parse_mode`	`DEFAULT`	global parse mode — see Text Formatting
`link_preview_options`	`None`	default link preview behaviour for sent messages
`plugins`	`None`	Smart Plugins config — see Smart Plugins
`takeout`	`None`	run the session in takeout mode for bulk export