Pabal API

Pabal API (MTProto)

For building clients that connect to the server the same way the app does: connection details, the server public key, the sign-in flow, updates and what's supported.

The Pabal app talks to the server over MTProto 2.0. Read this page when you're building a program that connects the same way — another app, automation running on a user account, a research client. If you're building a bot, the simpler Bot API is enough.

Connection details

There's no HTTP transport, WebSocket transport or MTProxy yet. The client device's clock must be right — MTProto message IDs are derived from the time, so if the clock is far off, the server drops the messages.

Server public key

When an MTProto client first connects, it encrypts the auth key exchange with the server's RSA public key. Telegram clients have Telegram's public key built in, so to connect to Pabal you have to put in this key instead (or as well). This key stops other servers from pretending to be the Pabal server.

-----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

This key is created once, when the server first starts, and never changes. Check that the Loaded RSA key … (fingerprint …) value in the server log matches the fingerprint above.

Connecting with Telethon

This example uses Python's Telethon to sign in to a user account and send and receive messages. Sign up in the app first to create the account (see below).

# pabal_client.py — pip install telethon==1.42.0
# server-key.pem (the server public key downloaded above) in the same folder
import asyncio

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

rsa.add_key(open("server-key.pem").read(), old=False)          # the Pabal server's public key

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # sign-in is saved in 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("Phone number (+8210…): "))   # enter the code once, the first time
    me = await client.get_me()
    print(f"Signed in: {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

• Use Telethon 1.42. It's the version that speaks layer 216. Newer versions try to read responses with a higher layer and fail with TypeNotFoundError.
• Telethon blocks signing up new accounts (sign_up()). Sign up in the app, or call auth.signUp directly.
• The sign-in is saved in the pabal.session file, so you won't be asked for a code again. This file is the key to the account, so keep it safe.

Sign-in flow

Receiving updates

• Real time: while the connection is open, the server immediately sends new messages, edits and deletions as updateShortMessage and updates. The session that sent a request gets the result as the RPC response, so the same thing isn't pushed to it a second time.
• pts: each user's changes get a sequence number (pts). If there's a gap in the pts a client receives, it has missed something.
• Catching up: remember the current pts with updates.getState, and when you reconnect, call updates.getDifference(pts, date, qts) to get the new messages and deletions in between, along with the related users and groups. If the client's pts is ahead of the server's (for example, when the server's data has been reset), you get differenceTooLong; reload the chat list in that case.
• Libraries such as Telethon take care of all this for you.

IDs and peers

Store access_hash exactly as the server gives it to you and use it from there (it comes along with username lookups, chat lists and updates).

Files

• Uploading: upload parts with upload.saveFilePart and reference them with inputFileUploaded…. upload.saveBigFilePart for large files doesn't exist yet, so the practical limit is 10 MB.
• Sending: messages.sendMedia with inputMediaUploadedPhoto (a new photo) or inputMediaPhoto (a photo already on the server). Other media give MEDIA_INVALID.
• Downloading: upload.getFile with inputPhotoFileLocation (message photos) or inputPeerPhotoFileLocation (profile photos). Up to 1 MB at a time.
• Profile photos: photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos.
• Photos are stored in one size only, the original (no separate thumbnails are generated).

What's supported

The server has handlers for 408 layer 216 methods and can read requests for all of them, but the methods below are the ones verified end to end with real clients. The rest answer in the right format, but their contents may be empty or may not be recorded.

We have also confirmed that the official Telegram Desktop 6.2.6 works without modification for signing up, signing in, chats, photos, groups and reconnecting. The roughly 60 methods the app calls at startup have their response formats checked separately.

Errors

Errors arrive as a standard rpc_error (error_code + error_message). error_message is always made of uppercase letters, digits and underscores (PEER_ID_INVALID), followed by : description when needed.

Not available yet

• Channels and supergroups (channels.* answers, but doesn't display properly in the app), secret chats, calls
• Media other than photos, upload.saveBigFilePart, thumbnails
• Two-step verification (SRP) — it can't be set up, and actions that require two-step verification are refused
• HTTP and WebSocket transports, MTProxy, sending msgs_ack, replacing bad_server_salt
• Splitting across several servers — a single server handles all of DCs 1–5

Connecting the official Telegram app to Pabal

The Telegram app builds the server address and public key into itself at build time. So instead of changing a setting, you have to modify the source and rebuild it. That's how the Pabal app (Pabal.app) was made. If you're a server operator, see Server installation — connecting the app.