The short answer
- 1A layer is the API's version number; declaring it keeps older apps working.
- 2Wrap the first request: invokeWithLayer, then initConnection, then the real request.
- 3Use an honest device name; users see it in their Devices list.
In this article
Layers: the API's version numbers
The Telegram API's methods and data shapes (its schema) change as features are added. Each set of changes gets the next number in sequence, called a layer. When your app declares "I speak layer N", the server answers in that layer's shapes, so older apps keep working. How to read layer numbers is in reading the TL schema and layers.
Two wrappers around your first request
The first request you send after connecting is wrapped like this: the outer layer declares the layer, the next one introduces your app, and the innermost part is the request you actually wanted to make.
invokeWithLayer(layer = the layer your app uses,
initConnection(app details…,
help.getConfig())) <- the request you actually wanted| Sent in initConnection | Meaning |
|---|---|
api_id | Your app's number from my.telegram.org; see getting an api_id |
device_model, system_version | Device name and OS version, shown in the user's Devices list |
app_version | Your app's version |
system_lang_code, lang_pack, lang_code | The device language, and the translation pack and language your app uses |
Send it again every time the app restarts and whenever these values change.
Other wrapper methods
| Wrapper | When to use it |
|---|---|
invokeAfterMsg / invokeAfterMsgs | Process this request only after an earlier one, keeping order without waiting for the answer |
invokeWithoutUpdates | Do not receive updates on this connection, for example a file-only connection |
invokeWithTakeout | Make requests inside a user data export (takeout) session |
With guaranteed ordering, a request blocked for too long comes back with an error asking you to resend it, and if the earlier request failed you get an error saying so. Handle them by error name; see reading API errors.
Compress large requests
You can send a request compressed with gzip. The official documentation advises against compressing data that is already compressed, such as photos and videos, or very short messages.
What TDLib handles for you
TDLib sends the layer and initConnection for you; you only pass your app details as parameters. See building TDLib.
FAQ
What is a layer in the Telegram API?
A version number for the API schema. Your app declares the layer it uses, and the server answers in that version's shapes.
Why do I need initConnection?
It tells the server about your app and device; the first request after connecting must be wrapped in it.
Does TDLib handle layers for me?
Yes. TDLib sends the layer and initConnection; you only pass your app details.
Sources
At a glance
- 1Layer
Declared with invokeWithLayer on the first request.
- 2initConnection
api_id, device, app version and language details.
- 3Wrappers
invokeAfterMsg for order, invokeWithoutUpdates for file connections.
Updated
