API Pabal

API Pabal (MTProto)

Pour créer un client qui se connecte au serveur comme l'application : informations de connexion, clé publique du serveur, flux d'authentification, mises à jour, périmètre pris en charge.

L'application Pabal communique avec le serveur en MTProto 2.0. Consultez cette page si vous créez un programme qui se connecte de la même façon : une autre application, une automatisation qui tourne avec un compte utilisateur, un client de recherche. Pour créer un bot, la Bot API, plus simple, suffit.

Informations de connexion

Les transports HTTP et WebSocket ainsi que MTProxy ne sont pas encore disponibles. L'horloge de l'appareil client doit être à l'heure : les numéros de message MTProto sont dérivés de l'heure, et si l'horloge est très décalée, le serveur rejette les messages.

Clé publique du serveur

Lors de sa première connexion, un client MTProto chiffre l'échange de clé d'autorisation avec la clé publique RSA du serveur. Les clients Telegram intègrent la clé publique de Telegram : pour se connecter à Pabal, ils doivent intégrer cette clé à la place (ou en plus). C'est elle qui empêche un autre serveur de se faire passer pour le serveur Pabal.

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA4hH74xPQsUwr/pyXPdF4tVicYr6QbfeDrKC7mUOVrPLSL4FtmgGn
w+O4u6lVvOf3Udd1KY6+OL4fUZdMBlLzwsoGLoniiVR09dnvyXHE8LhQSS+i1LmI
oJbhQwXplLnUJf272fLXkD23e7ppKLkjYk+jeYObueCy5HYMSThklVeXEzbZVGZv
47o/mjU2vyFoRpa6wCIE4rpj1UIPtOMpekMI/TocIlGVJ+ch6cAVNxIDro53a1eG
/1oZRLQH4oViEGxeMMjBMY5gk5HPkZvjbqy4h8TjXEz7O5o0BRsSqG/OPtP/dRQV
X4ewPhj2WCU4e6l5X59ZKIcv4sQLOwClqQIDAQAB
-----END RSA PUBLIC KEY-----

curl -s -o server-key.pem https://pabal.me/docs/server-key.pem

Cette clé est générée une seule fois, au premier démarrage du serveur, et ne change plus. Vérifiez que la valeur Loaded RSA key … (fingerprint …) des journaux du serveur correspond à l'empreinte ci-dessus.

Se connecter avec Telethon

Exemple avec Telethon en Python : connexion à un compte utilisateur, puis envoi et réception de messages. Créez d'abord le compte en vous inscrivant depuis l'application (voir plus bas).

# pabal_client.py — pip install telethon==1.42.0
# server-key.pem (la clé publique du serveur téléchargée plus haut) dans le même dossier
import asyncio

from telethon import TelegramClient, events
from telethon.crypto import rsa

rsa.add_key(open("server-key.pem").read(), old=False)          # clé publique du serveur Pabal

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # connexion enregistrée dans pabal.session
client.session.set_dc(2, "122.34.175.215", 8443)


@client.on(events.NewMessage(incoming=True))
async def show(event):
    sender = await event.get_sender()
    print(f"{sender.first_name}: {event.raw_text}")


async def main():
    await client.start(phone=lambda: input("Numéro de téléphone (+336…) : "))   # code à saisir la première fois seulement
    me = await client.get_me()
    print(f"Connecté : {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

• Utilisez Telethon 1.42 : c'est la version qui parle la layer 216. Les versions plus récentes tentent de lire les réponses avec une layer plus élevée et échouent avec TypeNotFoundError.
• Telethon bloque l'inscription de nouveaux comptes (sign_up()). Inscrivez-vous depuis l'application, ou appelez vous-même auth.signUp.
• La connexion est enregistrée dans le fichier pabal.session : le code ne vous sera plus demandé les fois suivantes. Ce fichier est la clé de votre compte : protégez-le.

Flux de connexion

Recevoir les mises à jour

• Temps réel : tant que la connexion est ouverte, le serveur envoie aussitôt les nouveaux messages, modifications et suppressions sous forme de updateShortMessage et updates. La session qui a envoyé une requête en reçoit le résultat dans la réponse RPC : elle ne reçoit donc pas la même chose une seconde fois en push.
• pts : chaque changement reçoit un numéro d'ordre (pts), propre à chaque utilisateur. Si les pts reçus par le client présentent un trou, c'est qu'il a manqué quelque chose.
• Rattrapage : mémorisez le pts actuel avec updates.getState ; à la reconnexion, updates.getDifference(pts, date, qts) renvoie les nouveaux messages et suppressions survenus entre-temps, avec les utilisateurs et groupes concernés. Si le pts du client est en avance sur celui du serveur (par exemple parce que les données du serveur ont été réinitialisées), vous recevez differenceTooLong : rechargez alors la liste des discussions.
• Les bibliothèques comme Telethon gèrent tout cela automatiquement.

ID et pairs

Enregistrez tel quel l'access_hash fourni par le serveur et réutilisez-le (il accompagne les résolutions de nom d'utilisateur, la liste des discussions et les mises à jour).

Fichiers

• Téléversement : envoyez les morceaux avec upload.saveFilePart, puis référencez-les avec inputFileUploaded… Quant à upload.saveBigFilePart, destiné aux gros fichiers, il n'existe pas encore : la limite est donc en pratique de 10 Mo.
• Envoi : messages.sendMedia avec inputMediaUploadedPhoto (nouvelle photo) ou inputMediaPhoto (photo déjà présente sur le serveur). Les autres médias renvoient MEDIA_INVALID.
• Réception : upload.getFile avec inputPhotoFileLocation (photo d'un message) ou inputPeerPhotoFileLocation (photo de profil). 1 Mo au maximum par appel.
• Photo de profil : photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos.
• Les photos ne sont stockées qu'en une seule taille, celle de l'original (aucune miniature n'est générée).

Périmètre pris en charge

Le serveur dispose de gestionnaires pour 408 méthodes de la layer 216, et tous savent lire les requêtes ; mais seules les méthodes ci-dessous ont été vérifiées de bout en bout avec de vrais clients. Les autres répondent dans le bon format, mais leur contenu peut être vide ou ne pas être enregistré.

Nous avons aussi vérifié que Telegram Desktop 6.2.6 officiel fonctionne sans modification pour l'inscription, la connexion, les conversations, les photos, les groupes et la reconnexion. Le format de réponse des quelque 60 méthodes que l'application appelle au démarrage fait l'objet d'une vérification spécifique.

Erreurs

Les erreurs arrivent sous la forme standard rpc_error (error_code + error_message). error_message est toujours composé de majuscules, de chiffres et de tirets bas (PEER_ID_INVALID), suivi si nécessaire de : explication.

Ce qui n'existe pas encore

• Canaux et supergroupes (channels.* répond, mais ils ne s'affichent pas correctement dans l'application), conversations secrètes, appels
• Médias autres que les photos, upload.saveBigFilePart, miniatures
• Validation en deux étapes (SRP) — impossible à configurer, et les opérations qui l'exigent sont refusées
• Transports HTTP et WebSocket, MTProxy, envoi de msgs_ack, remplacement de bad_server_salt
• Répartition sur plusieurs serveurs — un seul serveur assure tous les DC de 1 à 5

Connecter l'application Telegram officielle à Pabal

L'application Telegram intègre l'adresse du serveur et la clé publique au moment de la compilation. Il faut donc modifier le code source et recompiler : un écran de réglages ne suffit pas. C'est ainsi qu'a été créée l'application Pabal (Pabal.app). Si vous êtes opérateur de serveur, consultez Installation du serveur — connecter l'application.