Using official APIs¶

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

Preparing¶

We need to import these things:

from opentele.td import TDesktop
from opentele.tl import TelegramClient
from opentele.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_Z
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 opentele.td import TDesktop
from opentele.tl import TelegramClient
from opentele.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", "thedemons"] as unique_ids
unique_string = "opentele library by thedemons"

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:

href="#__codelineno-10-1">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'} class="n">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'} class="n">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'} class="n">unique_id = "thedemons" {'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'} class="n">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'}

The class links on this page point at upstream's documentation

opentele-ng has no API reference of its own yet, so APIData, the API templates and TelegramClient / TDesktop above link to opentele.readthedocs.io — the generated reference for the original project, thedemons/opentele, last built in 2022. Class and method names are unchanged in this fork, so the signatures still apply, but the device and app fingerprints shipped in those templates have been refreshed many times since; the current ones live in src/devices.json, and the changes are listed in the CHANGELOG.