Configuration

TelegramClient needs three things to run: your API credentials, somewhere to persist the session, and (optionally) which data center to bootstrap from. This page covers all three.

API credentials

TelegramClient.fromEnv() is the easiest way to supply API_ID/API_HASH — it loads them from a .env-style file using penv:

final client = TelegramClient.fromEnv(); // reads .env next to your script

Pass a different file name with envFile:

final client = TelegramClient.fromEnv(envFile: '.env.production');

Or skip .env entirely and construct TelegramClient directly — useful if credentials come from a secrets manager, environment variables, or a config system of your own:

final client = TelegramClient(
  apiId: 1234567,
  apiHash: '0123456789abcdef0123456789abcdef',
);

Session storage

By default, sessions are persisted to ptgc.session.json next to your script via FileSessionStore. Point it somewhere else:

final client = TelegramClient.fromEnv(
  sessionStore: const FileSessionStore('sessions/my-account.json'),
);

Or keep nothing on disk at all with MemorySessionStore — handy for tests and short-lived scripts:

final client = TelegramClient.fromEnv(
  sessionStore: MemorySessionStore(),
);

Implement SessionStore yourself to persist sessions to a database or secrets manager — see Session Storage and the Custom Session Store example. Treat session contents as sensitive: anyone who has them can act as the logged-in account without a password or code.

Bootstrap data centers

TelegramClient starts by connecting to a default data center and, if Telegram redirects it (a *_MIGRATE_* error), migrates automatically and remembers the new one for next time. You only need to touch this if the defaults are unreachable from where your code runs — see Custom Bootstrap Data Centers:

final client = TelegramClient(
  apiId: apiId,
  apiHash: apiHash,
  bootstrapDataCenters: [DataCenter(2, '149.154.167.51', 443)],
);