Sessions

In Telethon, the word session is used to refer to the set of data needed to connect to Telegram. This includes the server address of your home data center, as well as the authorization key bound to an account. When you first connect to Telegram, an authorization key is generated to encrypt all communication. After login, Telegram remembers this authorization key as logged-in, so you don’t need to login again.

Important

Do not leak the session file! Anyone with that file can login to the account stored in it. If you believe someone else has obtained this file, immediately revoke all active sessions from an official client.

Some auxiliary information such as the user ID of the logged-in user is also kept.

The update state, which can change every time an update is received from Telegram, is also stored in the session. Telethon needs this information to catch up on all missed updates while your code was not running. This is why it’s important to call Client.disconnect(). Doing so flushes all the update state to the session and saves it.

Session files

Telethon defaults to using SQLite to store the session state. The session state is written to .session files, so make sure your VCS ignores them! To make sure the .session file is saved, you should call Client.disconnect() before exiting the program.

The first parameter in the Client constructor is the session to use. You can use a str, a pathlib.Path or a session.Storage. The string or path are relative to the Current Working Directory. You can use absolute paths or relative paths to folders elsewhere. The .session extension is automatically added if the path has no extension.

Session storages

The session.Storage abstract base class defines the required methods to create custom storages. Telethon comes with two built-in storages:

• SqliteSession. This is used by default when a string or path is used.

• MemorySession. This is used by default when the path is None. You can also use it directly when you have a Session instance. It’s useful when you don’t have file-system access.

If you would like to store the session state in a different way, you can subclass session.Storage. You may also find custom third-party session storages in Telethon’s wiki. Be careful with any third-party code you install, as they could steal the login credentials. Only use session storages you trust, and pin the specific versions you have audited.

Some Python installations do not have the sqlite3 module. In this case, attempting to use the default SqliteSession will fail. If this happens, you can try reinstalling Python. If you still don’t have the sqlite3 module, you should use a different storage.