Session JSON Format

The .session + .json format is a portable way to store Telegram sessions. The .session file contains the Telethon SQLite session (auth keys, DC info), while the .json sidecar contains all API and device fingerprint metadata. This format makes sessions easy to transfer, back up, and manage across tools.

opentele2 supports both importing (reading .session + .json into a working client) and exporting (saving any client to .session + .json).

Preparing

• You need both a .session file and a matching .json file with the same base name.
• We need to import these things:

  from opentele2.td import TDesktop
  from opentele2.tl import TelegramClient
  from opentele2.api import API, APIData, UseCurrentSession, CreateNewSession
  import asyncio
  

• And we need to put the main code inside an async function:

  async def main():
      # PUT EXAMPLE CODE HERE
  
  asyncio.run(main())
  

JSON file structure

The .json file contains API credentials and device fingerprint data:

{
    "app_id": 2040,
    "app_hash": "b18441a1ff607e10a989891a5462e627",
    "device": "Desktop",
    "sdk": "Windows 11",
    "app_version": "5.12.3 x64",
    "system_lang_pack": "en-US",
    "system_lang_code": "en-US",
    "lang_pack": "tdesktop",
    "lang_code": "en",
    "session_file": "my_account",
    "twoFA": null,
    "id": 123456789,
    "phone": "+1234567890",
    "username": "myuser",
    "is_premium": false
}

Field mapping

JSON field	APIData field	Description
app_id	api_id	Telegram API ID
app_hash	api_hash	Telegram API hash
device	device_model	Device name or User-Agent
sdk	system_version	OS / SDK version
app_version	app_version	Application version string
system_lang_pack	system_lang_code	System language with region
lang_pack	lang_pack	Client lang pack identifier
lang_code	lang_code	UI language code
session_file	—	Base filename (no extension)

Importing a session

Using TelegramClient

# Import from .session + .json (pass path with or without extension)
client = await TelegramClient.FromSessionJson("path/to/my_account")

# The client now has the auth key, DC info, and API fingerprint loaded.
# Connect to Telegram:
await client.connect()
await client.PrintSessions()

You can also pass the .session extension explicitly:

client = await TelegramClient.FromSessionJson("path/to/my_account.session")

Or specify the JSON path separately:

client = await TelegramClient.FromSessionJson(
    "path/to/my_account",
    json_path="path/to/custom_config.json"
)

Using TDesktop

# Import as TDesktop (converts internally via TelegramClient)
tdesk = await TDesktop.FromSessionJson("path/to/my_account")

Exporting a session

From TelegramClient

# Save current session to .session + .json files
session_path, json_path = await client.SaveSessionJson("output/my_account")
# Creates: output/my_account.session + output/my_account.json

If the client is connected, you can also fetch live user info:

session_path, json_path = await client.SaveSessionJson(
    "output/my_account",
    fetch_user_info=True  # populates id, phone, username, is_premium
)

From TDesktop

# Load from tdata, then export to .session + .json
tdesk = TDesktop(r"C:\Users\<username>\AppData\Roaming\Telegram Desktop\tdata")
session_path, json_path = await tdesk.SaveSessionJson("output/my_account")

Converting between formats

tdata to .session + .json

from opentele2.td import TDesktop
from opentele2.api import UseCurrentSession
import asyncio

async def main():
    # Load tdata
    tdesk = TDesktop(r"C:\path\to\tdata")
    assert tdesk.isLoaded()

    # Export to .session + .json
    session_path, json_path = await tdesk.SaveSessionJson("output/my_account")
    print(f"Exported: {session_path}, {json_path}")

asyncio.run(main())

.session + .json to tdata

from opentele2.td import TDesktop
from opentele2.tl import TelegramClient
from opentele2.api import UseCurrentSession
import asyncio

async def main():
    # Import from .session + .json
    client = await TelegramClient.FromSessionJson("my_account")

    # Convert to TDesktop and save as tdata
    tdesk = await client.ToTDesktop(flag=UseCurrentSession)
    tdesk.SaveTData("output/tdata")

asyncio.run(main())

.session + .json round-trip

from opentele2.tl import TelegramClient
import asyncio

async def main():
    # Import
    client = await TelegramClient.FromSessionJson("original/my_account")

    # Export to a new location
    await client.SaveSessionJson("backup/my_account")

    # Re-import from backup (auth key and DC preserved exactly)
    client2 = await TelegramClient.FromSessionJson("backup/my_account")

asyncio.run(main())

Using APIData helpers directly

You can also work with the JSON format programmatically:

from opentele2.api import APIData
import json

# Parse JSON into APIData
with open("my_account.json") as f:
    data = json.load(f)

api = APIData.from_json(data)
print(api.api_id, api.device_model, api.lang_pack)

# Serialize APIData back to JSON
exported = api.to_json(extra={"id": 12345, "session_file": "my_account"})
with open("exported.json", "w") as f:
    json.dump(exported, f, indent=2)