The short answer
- 1A TL line is constructor#number fields = Type.
- 2flags:# bits mark which optional fields are present; read only those, in order.
- 3Track changes per layer in the official layer changelog instead of a translated list.
In this article
The schema is the API's list of blueprints
Every data shape and method in the Telegram API is written one per line in a short notation called TL (Type Language). That list is the schema. The official schema page (core.telegram.org/schema) is not a manual written for people; it is hundreds of these lines. Once you can read them, you do not need a translated list of methods. The schema page shows the current layer number.
Reading one line
The line below is invented for this explanation; the name does not exist in the real schema.
sampleNote#1a2b3c4d id:long text:string = Note;| Part | Meaning |
|---|---|
sampleNote | The constructor name; starts with a lowercase letter |
#1a2b3c4d | The constructor number (32-bit, hexadecimal). It comes first in the binary data and says "this is a sampleNote" |
id:long text:string | Field names and their types |
= Note | The type this constructor produces; starts with a capital letter |
One type can have several constructors. A "photo" type might have both a "photo" and an "empty photo" constructor, so you tell which one you received from the constructor number.
Optional fields: flags
sampleMessage#5e6f7a8b flags:# pinned:flags.0?true reply_to:flags.1?int text:string = Message;flags:#is a number field whose bits say which optional fields are present.reply_to:flags.1?intis present only when bit 1 offlagsis set.pinned:flags.0?true: a field of typetruecarries no value; the bit itself is the yes or no.
When reading, look at flags first and read only the fields whose bits are set, in order. Miss one and every field after it shifts, and the whole thing is misread.
The two sections of the list, and Vector
| Section or notation | Meaning |
|---|---|
Above ---functions--- | Data shapes (types and constructors) |
Below ---functions--- | Methods you can call; the type at the end of the line is what you get back |
Vector<User> | A list of several User values |
Following layers and what changed
Each time the schema changes, the layer number goes up by one. Your app declares the layer it uses when it connects; see layers and initConnection. What changed in each layer is in the official layer changelog (core.telegram.org/api/layers). A machine-readable JSON version of the schema also exists for feeding into code generators.
TDLib has its own schema, td_api.tl. The notation is the same, but names and structure are arranged to be easier to use; see building TDLib.
Why knowing how to read it is enough
Methods and constructors are added and changed with every layer, so a translated list goes out of date quickly. That is why the developer guides on this site teach how to read the schema rather than copying the method list. For the overall structure, start with MTProto at a glance.
FAQ
What is the TL schema in Telegram?
A list written in Type Language that defines every data shape and method in the Telegram API, one per line.
What does flags.1?int mean?
The field exists only when bit 1 of the flags field is set.
Where do I see what changed between layers?
In the official layer changelog at core.telegram.org/api/layers.
Sources
At a glance
- 1Line
Lowercase constructor, hex ID, typed fields, capitalised type.
- 2flags
flags.N?type fields exist only when bit N is set.
- 3Layers
Each schema change bumps the layer; check the changelog.
Updated
