The Full API
The API surface offered by Telethon is not exhaustive. Telegram is constantly adding new features, and both implementing and documenting custom methods would an exhausting, never-ending job.
Telethon concedes to this fact and implements only commonly-used features to keep a lean API. Access to the entirity of Telegram’s API via Telethon’s Raw API is a necessary evil.
telethon._tl module has a leading underscore to signal that it is private.
It is not covered by the semver guarantees of the library, but you may need to use it regardless.
Client doesn’t offer a method for what you need, using the Raw API is inevitable.
Invoking Raw API methods
The Raw API can be invoked in a very similar way to other client methods:
from telethon import _tl as tl
was_reset = await client(tl.functions.account.reset_wall_papers())
telethon._tl.functions you will find a function for every single RPC supported by Telegram.
The parameters are keyword-only and do not have defaults.
Whatever arguments you pass is exactly what Telegram will receive.
Whatever is returned is exactly what Telegram responded with.
All functions inside
telethon._tl.functions will return the serialized request.
When calling a
Client instance with this request as input, it will be sent to Telegram and wait for a response.
Multiple requests may be in-flight at the same time, specially when using
Telethon will attempt to combine these into a single “container” when possible as an optimization.
Exploring the Raw API
This means you can print any response and get the Python representation of that object.
All types are proper classes with attributes. You do not need to use a regular expression on the string representation to access the field you want.
invite = await client(tl.functions.messages.check_chat_invite(hash='aBcDeF'))
if isinstance(invite, tl.types.ChatInviteAlready):
telethon._tl module is not documented here because it would greatly bloat the documentation and make search harder.
Instead, there are multiple alternatives:
Use Telethon’s separate site to search in the Telethon Raw API. This is the recommended way. It also features auto-generated examples.
Use an editor with autocompletion support.