470 lines
22 KiB
YAML
470 lines
22 KiB
YAML
# This file contains additional descriptions for TL objects,
|
||
# for example for objects/fields that don't have a description
|
||
# from Telegram documentation.
|
||
#
|
||
# By default, these descriptions are used as a fallback,
|
||
# but can also be used to overwrite original documentation.
|
||
#
|
||
# This file is licensed under MIT license.
|
||
|
||
# Big thanks to Durov team for not providing complete docs like this in the first place,
|
||
# and instead spreading the docs across dozens of pages without proper formatting or anything.
|
||
|
||
# Override TL objects' (classes/methods) description, or their arguments' descriptions.
|
||
# Type is defined by the first 2 symbols in key ("o_" for class/method, "u_" for union)
|
||
objects:
|
||
o_mt_reqPq:
|
||
desc: >
|
||
Request for the first step of Authorization key derivation process.
|
||
This method is deprecated, use {@link tl.mtproto.RawReqPqMultiRequest} instead.
|
||
The difference is that when using this, only one server key is returned, while
|
||
`req_pq_multi` will return multiple.
|
||
arguments:
|
||
nonce: Randomly generated number (32-bit) that will be used in the later steps
|
||
o_mt_reqPqMulti:
|
||
desc: >
|
||
Request for the first step of Authorization key derivation process.
|
||
arguments:
|
||
nonce: Randomly generated number that will be used in the later steps
|
||
o_mt_resPQ:
|
||
desc: Response for the first step of Authorization key derivation process
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Random number generated by the server, used in the later steps
|
||
pq: >
|
||
Big endian representation of a natural number, which is a product
|
||
of two different odd prime numbers. Normally, this value is `<= 2^63-1`.
|
||
Client is expected to decompose this product to `p` and `q`.
|
||
serverPublicKeyFingerprints: |
|
||
List of public RSA key fingerprints, which are computed as follows:
|
||
- First, the modulus and the exponent are extracted from the key
|
||
- Then, the following TL type is written: `rsa_public_key n:string e:string = RSAPublicKey`
|
||
- This is a bare type, meaning there's no 4-byte type number before it
|
||
- `n` is the modulus, `e` is the exponent, encoded as big-endian
|
||
- Finally, SHA1 is computed, and its last 8 bytes are taken and parsed as LE long
|
||
(i.e. `parse_int64_le(sha1(rsa_public_key).slice(-8))`)
|
||
|
||
Client is expected to choose out of those keys any single one that it has
|
||
embedded in itself and return one of them in the following request.
|
||
o_mt_reqDHParams:
|
||
desc: Request for the second step of Authorization key derivation process.
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
p: Big endian encoded first factor. Note - `p < q`
|
||
q: Big endian encoded second factor. Node - `p < q`
|
||
publicKeyFingerprint: Fingerprint of the RSA key that the client has chosen
|
||
encryptedData: |
|
||
Encrypted payload, obtained as follows:
|
||
- Let `newNonce` be a random 32-bit number
|
||
- Let `data` be a serialization of either {@link tl.mtproto.RawP_q_inner_data}
|
||
or {@link tl.mtproto.RawP_q_inner_data_temp} with the generated `newNonce`
|
||
- `dataWithHash = concat(sha1(data), data, random_bytes(235 - data.length))`
|
||
- `encryptedData = dataWithHash ^ key.exponent % key.modulus`, where `key` is the
|
||
server public key which was chosen
|
||
o_mt_p_q_inner_data:
|
||
desc: Inner data used for {@link tl.mtproto.RawReqDHParamsRequest}
|
||
arguments:
|
||
pq: Original product of `p` and `q` sent by the server
|
||
p: Big endian encoded first factor. Note - `p < q`
|
||
q: Big endian encoded second factor. Node - `p < q`
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
newNonce: New client nonce generated
|
||
o_mt_p_q_inner_data_temp:
|
||
desc: >
|
||
Inner data used for {@link tl.mtproto.RawReqDHParamsRequest}.
|
||
Unlike {@link tl.mtproto.RawP_q_inner_data}, this is used to generate
|
||
a temporary key.
|
||
arguments:
|
||
pq: Original product of `p` and `q` sent by the server
|
||
p: Big endian encoded first factor. Note - `p < q`
|
||
q: Big endian encoded second factor. Node - `p < q`
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
newNonce: New client nonce generated
|
||
expiresIn: >
|
||
Maximum number of seconds that this key will be valid for.
|
||
The server might discard the key earlier.
|
||
o_mt_server_DH_params_fail:
|
||
desc: PQ decomposition was incorrect, try again.
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
o_mt_server_DH_params_ok:
|
||
desc: PQ decomposition was correct, server-side variables for DH are returned
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
encryptedAnswer: |
|
||
Encrypted DH parameters, obtained as follows:
|
||
- Let `answer` be a serialization of {@link tl.mtproto.RawServer_DH_inner_data}
|
||
- `hash1 = sha1(concat(newNonce, serverNonce))`
|
||
- `hash2 = sha1(concat(serverNonce, newNonce))`
|
||
- `hash3 = sha1(concat(newNonce, newNonce))`
|
||
- `key = concat(hash1, hash2.slice(0, 12))`
|
||
- `iv = concat(hash2.slice(12, 20), hash3, newNonce.slice(0, 4))`
|
||
- `encryptedAnswer = aes256_ige_encrypt(answer, key, iv)
|
||
o_mt_server_DH_inner_data:
|
||
desc: >
|
||
Inner data that is returned in {@link tl.mtproto.RawServer_DH_params_ok},
|
||
containing server-side variables for Diffie-Hellman exchange
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
g: '`g` number (generator) used for Diffie-Hellman'
|
||
dhPrime: '`p` prime number (modulus) used for Diffie-Hellman'
|
||
gA: '`gA` number (`gA = g ^ A % p`, where `A` is server secret) used for Diffie-Hellman'
|
||
serverTime: Server UNIX timestamp (in seconds)
|
||
o_mt_setClientDHParams:
|
||
desc: Request containing encrypted client-side variables for Diffie-Hellman exchange
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
encryptedData: |
|
||
Encrypted DH parameters, obtained as follows:
|
||
- Let `B` be a random 2048-bit (256 bytes) integer
|
||
- `gB = g ^ B % dhPrime` (Diffie-Hellman)
|
||
- Let `data` be a serialization of {@link tl.mtproto.RawClient_DH_inner_data}
|
||
- `dataWithHash = concat(sha1(data), data, padding))`, where `padding` is
|
||
0-15 random bytes, such that `dataWithHash.length` is divisible by 16
|
||
- `encryptedData = aes256_ige_encrypt(dataWithHash, key, iv)`, where `key` and `iv`
|
||
are the same as ones used in {@link tl.mtproto.RawServer_DH_params_ok}
|
||
o_mt_client_DH_inner_data:
|
||
desc: >
|
||
Inner data of {@link tl.mtproto.RawSetClientDHParamsRequest},
|
||
containing client-side variables for Diffie-Hellman exchange
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
retryId: >
|
||
Retry ID. When requesting for the first time, `0`,
|
||
then last `authKeyAuxHash` is used
|
||
gB: '`gB` number (`gB = g ^ B % p`, where `B` is client secret) used for Diffie-Hellman'
|
||
с_mt_dh_gen_ok:
|
||
desc: >
|
||
DH exchange was successful, and auth key is `gA ^ b % dhPrime`,
|
||
and `authKeyAuxHash = sha1(authKey).slice(0, 8)`
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
newNonceHash1: >
|
||
Nonce hash, computed as follows: `sha1(concat([newNonce, [0x01], authKeyAuxHash])`
|
||
o_mt_dh_gen_retry:
|
||
desc: >
|
||
DH exchange need to be retried. Current auth key is `gA ^ b % dhPrime`,
|
||
and `authKeyAuxHash = sha1(authKey).slice(0, 8)`, but they will change.
|
||
|
||
When this is received, you are expected to send
|
||
another {@link tl.mtproto.RawSetClientDHParamsRequest}.
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
newNonceHash2: >
|
||
Nonce hash, computed as follows: `sha1(concat([newNonce, [0x02], authKeyAuxHash])`
|
||
o_mt_dh_gen_fail:
|
||
desc: DH exchange failed. You should restart the entire authorization flow.
|
||
arguments:
|
||
nonce: Client nonce that was generated earlier
|
||
serverNonce: Server nonce that was received earlier
|
||
newNonceHash3: >
|
||
Nonce hash, computed as follows: `sha1(concat([newNonce, [0x03], authKeyAuxHash])`
|
||
o_mt_rpc_result:
|
||
desc: Result of an RPC call
|
||
arguments:
|
||
reqMsgId: Requesting message ID
|
||
result: Result of the call
|
||
o_mt_rpc_error:
|
||
desc: >
|
||
RPC call resulted in an error, information about that error.
|
||
Error is still a result, and thus it is sent as a `result`
|
||
of {@link tl.mtproto.RawRpc_result}
|
||
arguments:
|
||
errorCode: Numeric error code (like 404)
|
||
errorMessage: String error code
|
||
с_mt_rpc_answer_unknown:
|
||
description: Nothing is known about this RPC call
|
||
o_mt_rpc_answer_dropped_running:
|
||
desc: >
|
||
Response was canceled while the RPC query was being processed
|
||
(where the RPC query itself was still fully processed); in this case,
|
||
the same rpc_answer_dropped_running is also returned in response to
|
||
the original query, and both of these responses require
|
||
an acknowledgment from the client.
|
||
o_mt_rpc_answer_dropped:
|
||
desc: The RPC response was removed from the server’s outgoing queue
|
||
arguments:
|
||
msgId: Message ID of the RPC response
|
||
seqNo: Seq NO of the RPC response
|
||
bytes: Length in bytes of the RPC response
|
||
o_mt_future_salt:
|
||
desc: Information about a single future server salt
|
||
arguments:
|
||
validSince: UNIX time in seconds from when this salt will be used
|
||
validUntil: UNIX time in seconds until which this salt will be used
|
||
salt: The server salt itself
|
||
o_mt_future_salts:
|
||
desc: Information about future server salts
|
||
arguments:
|
||
reqMsgId: Requesting message ID
|
||
now: Current server UNIX timestamp in seconds
|
||
salts: List of future salts
|
||
o_mt_pong:
|
||
desc: Response to a {@link tl.mtproto.RawPingRequest}
|
||
arguments:
|
||
msgId: Message ID that contained `mt_ping`
|
||
pingId: Ping ID that was sent in `mt_ping`
|
||
o_mt_ping:
|
||
desc: Ping a server to test connection
|
||
arguments:
|
||
pingId: Random ping ID
|
||
o_mt_pingDelayDisconnect:
|
||
desc: >
|
||
Works like ping. In addition, after this is received,
|
||
the server starts a timer which will close the current connection
|
||
`disconnectDelay` seconds later unless it receives a new message
|
||
of the same type which automatically resets all previous timers.
|
||
|
||
If the client sends these pings once every 60 seconds, for example,
|
||
it may set `disconnect_delay` equal to 75 seconds.
|
||
arguments:
|
||
pingId: Random ping ID
|
||
disconnectDelay: Disconnect delay in seconds
|
||
o_mt_destroy_session:
|
||
desc: >
|
||
Used by the client to notify the server that it may forget the
|
||
data from a different session belonging to the same user
|
||
(i.e. with the same `authKeyId`).
|
||
|
||
The result of this being applied to the current session is undefined.
|
||
arguments:
|
||
sessionId: Old session ID
|
||
o_mt_destroy_session_ok:
|
||
desc: Session was succesfully destroyed
|
||
arguments:
|
||
sessionId: Old session ID
|
||
o_mt_destroy_session_none:
|
||
desc: Session was not destroyed because it does not exist
|
||
arguments:
|
||
sessionId: Old session ID
|
||
o_mt_new_session_created:
|
||
desc: >
|
||
The server notifies the client that a new session (from the server’s standpoint)
|
||
had to be created to handle a client message. If, after this, the server receives
|
||
a message with an even smaller `msg_id` within the same session, a similar
|
||
notification will be generated for this `msg_id` as well.
|
||
No such notifications are generated for high msg_id values.
|
||
|
||
This notification must be acknowledged by the client. It is necessary, for instance,
|
||
for the client to understand that there is, in fact, a “gap” in the stream of notifications
|
||
received from the server (the user may have failed to receive
|
||
notifications during some period of time).
|
||
|
||
Client should also resend all the messages that were sent before `firstMsgId`
|
||
arguments:
|
||
firstMsgId: First message ID that is known by the server to be from this session.
|
||
uniqueId: Random number generated by the server every time a session is (re-)created
|
||
serverSalt: Current server salt
|
||
o_mt_msg_container:
|
||
desc: A simple container that carries several messages
|
||
arguments:
|
||
messages: List of messages in the container
|
||
o_mt_message:
|
||
desc: A message in the container
|
||
arguments:
|
||
msgId: Original message ID
|
||
seqno: Original message seq No
|
||
bytes: Length of the message
|
||
body: Contents of the message
|
||
o_mt_msg_copy:
|
||
desc: A copy of a message
|
||
arguments:
|
||
origMessage: Original message
|
||
o_mt_gzip_packed:
|
||
desc: >
|
||
An object, which was gzipped.
|
||
|
||
At the present time, it is supported in the body
|
||
of an RPC response (i.e., as result in `rpc_result`)
|
||
and generated by the server for a limited number
|
||
of high-level queries. In addition, in the future
|
||
it may be used to transmit non-service messages
|
||
(i. e. RPC queries) from client to server.
|
||
arguments:
|
||
packedData: Gzipped contents of the message
|
||
o_mt_msgs_ack:
|
||
desc: >
|
||
Receipt of virtually all messages (with the exception of some purely
|
||
service ones as well as the plain-text messages used in the protocol
|
||
for creating an authorization key) must be acknowledged.
|
||
|
||
This requires the use of the this service message (not requiring an acknowledgment itself)
|
||
|
||
A server usually acknowledges the receipt of a message
|
||
from a client (normally, an RPC query) using an RPC response.
|
||
If a response is a long time coming, a server may first send a
|
||
receipt acknowledgment, and somewhat later, the RPC response itself.
|
||
|
||
A client normally acknowledges the receipt of a message
|
||
from a server (usually, an RPC response) by adding an acknowledgment
|
||
to the next RPC query if it is not transmitted too late (if it is
|
||
generated, say, 60-120 seconds following the receipt of a message
|
||
from the server). However, if for a long period of time there is no
|
||
reason to send messages to the server or if there is a large number of
|
||
unacknowledged messages from the server (say, over 16),
|
||
the client transmits a stand-alone acknowledgment.
|
||
arguments:
|
||
msgIds: IDs of messages to be acknowledged. Maximum 8192 IDs.
|
||
o_mt_bad_msg_notification:
|
||
desc: Used by the server to notify client that the sent message was incorrect.
|
||
arguments:
|
||
badMsgId: ID of the "bad" message
|
||
badMsgSeqno: Seq No of the "bad" message
|
||
errorCode: |
|
||
Error code. Known values:
|
||
- `16`: Message ID was too small. Most likely, client time is wrong, it would be
|
||
worthwhile to synchronize it using notification's message ID and re-send the
|
||
original message with the "correct" message ID or wrap it in a container
|
||
with a new message ID if the original message had waited too
|
||
long on the client to be transmitted.
|
||
- `17`: Message ID was too big. Similar to the previous case,
|
||
the client time has to be synchronized, and the message re-sent
|
||
- `18`: Incorrect two lower order msg_id bits. The server expects client
|
||
message ID to be divisible by 4.
|
||
- `19`: Container message ID is the same as the message ID of the previous message
|
||
- `20`: Message is too old, and it cannot be verified whether the server
|
||
has received a message with this ID or not
|
||
- `32`: Message seq No was too small (the server has already received a message
|
||
with a higher or same seq No)
|
||
- `33`: Message seq No was too big (the server has already received a message
|
||
with a lower or same seq No)
|
||
- `34`: An even seq No expected (not content-relevant), but odd received
|
||
- `35`: An odd seq No expected (content-relevant), but even received
|
||
- `48`: Incorrect server salt was used. In practice, `mt_bad_server_salt` is used instead.
|
||
- `64`: Incorrect container
|
||
o_mt_bad_server_salt:
|
||
desc: Used by the server to notify client that the sent message was incorrect.
|
||
arguments:
|
||
badMsgId: ID of the "bad" message
|
||
badMsgSeqno: Seq No of the "bad" message
|
||
errorCode: Always `48`
|
||
newServerSalt: New server salt to be used
|
||
o_mt_msg_resend_req:
|
||
desc: |
|
||
Explicit Request to Re-Send Messages
|
||
|
||
The remote party immediately responds by re-sending
|
||
the requested messages, normally using the same connection
|
||
that was used to transmit the query. If at least one message
|
||
with requested ID does not exist or has already been forgotten,
|
||
or has been sent by the requesting party (known from parity),
|
||
`MsgsStateInfo` is returned for all messages requested as if the
|
||
`MsgResendReq` query had been a `MsgsStateReq` query as well.
|
||
arguments:
|
||
msgIds: IDs of the messages to be resent (up to 8192 IDs)
|
||
o_mt_msg_resend_ans_req:
|
||
desc: |
|
||
Explicit Request to Re-Send Answers
|
||
|
||
The remote party immediately responds by re-sending *answers*
|
||
to the requested messages, normally using the same connection
|
||
that was used to transmit the query. `MsgsStateInfo` is returned
|
||
for all messages requested as if the `MsgResendReq` query had
|
||
been a `MsgsStateReq` query as well.
|
||
arguments:
|
||
msgIds: IDs of the messages answers to which should be resent (up to 8192 IDs)
|
||
o_mt_msgs_state_req:
|
||
desc: >
|
||
Request for Message Status Information. If either party has
|
||
not received information on the status of its outgoing
|
||
messages for a while, it may explicitly request it from the other party
|
||
arguments:
|
||
msgIds: IDs of the messages state of which should be sent (up to 8192 IDs)
|
||
o_mt_msgs_state_info:
|
||
desc: Informational Message regarding Status of Messages
|
||
arguments:
|
||
reqMsgId: Requesting message ID
|
||
info: |
|
||
Byte array containing exactly one byte for each message ID:
|
||
- `1`: nothing is known about the message (ID is too small, the other party may have forgotten it)
|
||
- `2`: message was not received (ID falls within the range of stored identifiers;
|
||
however, the other party has certainly not received a message like that)
|
||
- `3`: message not received (ID is too big; however, the other
|
||
party has certainly not received it yet)
|
||
- `4`: message received (note that this response is also at the same time a receipt acknowledgment)
|
||
- `+8`: message already acknowledged
|
||
- `+16`: message not requiring acknowledgment
|
||
- `+32`: RPC query contained in message being processed or processing already complete
|
||
- `+64`: content-related response to message already generated
|
||
- `+128`: other party knows for a fact that message is already received
|
||
o_mt_msgs_all_info:
|
||
desc: >
|
||
Voluntary Communication of Status of Messages. Either party may
|
||
voluntarily inform the other party of the status of the messages
|
||
transmitted by the other party.
|
||
arguments:
|
||
msgIds: Message IDs that the other party is being informed about
|
||
info: Byte array in the same format as {@link tl.mtproto.RawMsgs_state_info}
|
||
o_mt_msg_detailed_info:
|
||
desc: |
|
||
Extended Voluntary Communication of Status of One Message.
|
||
|
||
Normally used by the server to respond to the receipt of
|
||
a duplicate message ID, especially if a response to the
|
||
message has already been generated and the response is large.
|
||
If the response is small, the server may re-send the answer
|
||
itself instead. This message can also be used as a notification
|
||
instead of resending a large message.
|
||
arguments:
|
||
msgId: Original message ID that this message is informing about
|
||
answerMsgId: Message ID that was the response to that message
|
||
bytes: Size of the answer message
|
||
status: Always `0`, but this may change in the future
|
||
o_mt_msg_new_detailed_info:
|
||
desc: >
|
||
Similar to {@link tl.mtproto.RawMsg_detailed_info}, but
|
||
used to notify about messages that were created on the server
|
||
not in response to an RPC query (e.g. updates) and were transmitted
|
||
to the client some time ago, but not acknowledged
|
||
arguments:
|
||
answerMsgId: ID of the message that was sent by the server
|
||
bytes: Size of the answer message
|
||
status: Always `0`, but this may change in the future
|
||
o_mt_rpcDropAnswer:
|
||
desc: >
|
||
Cancellation of an RPC query.
|
||
In certain situations, the client does not want to receive a
|
||
response to an already transmitted RPC query, for example because
|
||
the response turns out to be long and the client has decided to do
|
||
without it because of insufficient link capacity. Simply interrupting
|
||
the connection will not have any effect because the server would re-send
|
||
the missing response at the first opportunity. Therefore, the client needs
|
||
a way to cancel receipt of the RPC response message, actually acknowledging
|
||
its receipt prior to it being in fact received, which will settle the server
|
||
down and prevent it from re-sending the response. However, the client does
|
||
not know the RPC response's message ID prior to receiving the response;
|
||
the only thing it knows is the requesting message ID, i.e. the message ID
|
||
of the relevant RPC query. Therefore, this special query is used
|
||
arguments:
|
||
reqMsgId: ID of a message containing an RPC query to be cancelled
|
||
|
||
|
||
# Override arguments wherever they are, based on the filters
|
||
arguments:
|
||
- name: gigagroup
|
||
filters:
|
||
- type: "true"
|
||
desc: Is this a broadcast group?
|
||
|
||
# Replace any description, based on regex. Used to fix typos.
|
||
regex:
|
||
- regex: \bchanel\b
|
||
repl: channel
|
||
- regex: \bgeoposition\b
|
||
repl: geo position
|
||
- regex: \bgeogroup\b
|
||
repl: geo group
|
||
- regex: \bunixdate\b|Unix timestamp
|
||
repl: UNIX timestamp in seconds
|
||
- regex: \bstickerset\b
|
||
repl: stickerset
|