Using official APIs¶

This example will show you how to use Telethon with official APIs.

Preparing¶

We need to import these things:

from opentele2.td import TDesktop
from opentele2.tl import TelegramClient
from opentele2.api import API, 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())

Creating an official API ¶

Using the default built-in template for Telegram Android API:
```
api = API.TelegramAndroid
```

Randomize the API's device data:

# Randomize the device data
api = API.TelegramAndroid.Generate()

Randomize the API's device data with a unique_id:

# unique_id can be anything
# This will be used to ensure that it will generate the same data everytime.
# If not set then the data will be randomized each time we runs it.
api = API.TelegramAndroid.Generate(unique_id="telethon.session")

All the built-in API templates available:

api = API.TelegramDesktop
api = API.TelegramAndroid
api = API.TelegramAndroidX
api = API.TelegramIOS
api = API.TelegramMacOS
api = API.TelegramWeb_A
api = API.TelegramWeb_K
api = API.Webogram

Creating a TelegramClient using the API¶

From an existing session:

client = TelegramClient("telethon.session", api=api)
await client.connect()

From a tdata folder:

tdataFolder = r"C:\Users\<username>\AppData\Roaming\Telegram Desktop\tdata"
tdesk = TDesktop(tdataFolder)
assert tdesk.isLoaded()

client = TelegramClient.FromTDesktop(tdesk, session="telethon.session", flag=UseCurrentSession, api=api)

await client.connect()

Final result example¶

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

async def main():

    # Randomize the device data
    api = API.TelegramAndroid.Generate()

    client = TelegramClient("telethon.session", api=api)
    await client.connect()

asyncio.run(main())

Extra: Demonstrate the behavior of unique_id¶

def PrintAPI(api):
    print("    ", {"device_model": api.device_model, "system_version": api.system_version})

# Randomize using ["opentele", "library", "by", "DedInc"] as unique_ids
unique_string = "opentele library by DedInc"

for unique_id in unique_string.split(" "):
    print(f'\nunique_id = "{unique_id}"')

    for x in range(5):
        PrintAPI(API.TelegramAndroid.Generate(unique_id))

# Randomize without unique_id
print("\nNot using unique_id")
for x in range(5):
    PrintAPI(API.TelegramAndroid.Generate())

The result should look like this:

unique_id = "opentele"
    {'device_model': 'Samsung SM-A750FN', 'system_version': 'SDK 24'}
    {'device_model': 'Samsung SM-A750FN', 'system_version': 'SDK 24'}
    {'device_model': 'Samsung SM-A750FN', 'system_version': 'SDK 24'}
    {'device_model': 'Samsung SM-A750FN', 'system_version': 'SDK 24'}
    {'device_model': 'Samsung SM-A750FN', 'system_version': 'SDK 24'}

unique_id = "library"
    {'device_model': 'Samsung SM-J100G', 'system_version': 'SDK 30'}
    {'device_model': 'Samsung SM-J100G', 'system_version': 'SDK 30'}
    {'device_model': 'Samsung SM-J100G', 'system_version': 'SDK 30'}
    {'device_model': 'Samsung SM-J100G', 'system_version': 'SDK 30'}
    {'device_model': 'Samsung SM-J100G', 'system_version': 'SDK 30'}

unique_id = "by"
    {'device_model': 'Samsung GT-S6800', 'system_version': 'SDK 26'}
    {'device_model': 'Samsung GT-S6800', 'system_version': 'SDK 26'}
    {'device_model': 'Samsung GT-S6800', 'system_version': 'SDK 26'}
    {'device_model': 'Samsung GT-S6800', 'system_version': 'SDK 26'}
    {'device_model': 'Samsung GT-S6800', 'system_version': 'SDK 26'}

unique_id = "DedInc"
    {'device_model': 'Samsung SM-N930VL', 'system_version': 'SDK 29'}
    {'device_model': 'Samsung SM-N930VL', 'system_version': 'SDK 29'}
    {'device_model': 'Samsung SM-N930VL', 'system_version': 'SDK 29'}
    {'device_model': 'Samsung SM-N930VL', 'system_version': 'SDK 29'}
    {'device_model': 'Samsung SM-N930VL', 'system_version': 'SDK 29'}

Not using unique_id
    {'device_model': 'Samsung SM-A705FN', 'system_version': 'SDK 29'}
    {'device_model': 'Samsung SM-T330', 'system_version': 'SDK 30'}
    {'device_model': 'Huawei HUAWEI C8860E', 'system_version': 'SDK 23'}
    {'device_model': 'Huawei HUAWEI C8860E', 'system_version': 'SDK 29'}
    {'device_model': 'Huawei HUAWEI Y625-U32', 'system_version': 'SDK 25'}

Using web client APIs with browser fingerprints¶

Web client APIs (TelegramWeb_A, TelegramWeb_K, Webogram) now support Generate() to randomize the browser User-Agent sent as device_model.

Requires browserforge

Install with: pip install browserforge or pip install opentele2[web]

Basic usage¶

from opentele2.tl import TelegramClient
from opentele2.api import API
import asyncio

async def main():

    # Generate a random browser fingerprint for Web A
    api = API.TelegramWeb_A.Generate()

    client = TelegramClient("telethon.session", api=api)
    await client.connect()

asyncio.run(main())

All web clients¶

# Web Z — User-Agent as device_model, OS name as system_version
api = API.TelegramWeb_A.Generate()
print(api.device_model)     # "Mozilla/5.0 (Windows NT 10.0; ...) Chrome/145.0.0.0 Safari/537.36"
print(api.system_version)   # "Windows"

# Web A — same behavior as Web Z
api = API.TelegramWeb_A.Generate()

# Web K — User-Agent as device_model, navigator.platform as system_version
api = API.TelegramWeb_K.Generate()
print(api.system_version)   # "Win32" or "MacIntel"

# Webogram (legacy) — same style as Web K
api = API.Webogram.Generate()

Deterministic fingerprints with `unique_id`¶

# Same unique_id always produces the same fingerprint
api1 = API.TelegramWeb_A.Generate(unique_id="session_abc")
api2 = API.TelegramWeb_A.Generate(unique_id="session_abc")
assert api1.device_model == api2.device_model  # True

# Different unique_id = different fingerprint
api3 = API.TelegramWeb_A.Generate(unique_id="session_xyz")
# api3.device_model will differ from api1.device_model

# No unique_id = random each time
api4 = API.TelegramWeb_A.Generate()

After connecting, you can run consistency checks to verify that the session looks like a real official client:

from opentele2.consistency import ConsistencyChecker

api = API.TelegramWeb_A.Generate()
client = TelegramClient("telethon.session", api=api)
await client.connect()

checker = ConsistencyChecker(client)
report = await checker.run_all()
print(report.summary)

See Fingerprints & Consistency for full documentation.