API Pabal

API Pabal (MTProto)

Untuk membuat klien yang terhubung ke server dengan cara yang sama seperti aplikasi: informasi koneksi, kunci publik server, alur autentikasi, update, dan cakupan dukungan.

Aplikasi Pabal berkomunikasi dengan server menggunakan MTProto 2.0. Bacalah dokumen ini saat Anda membuat program yang tersambung dengan cara yang sama — aplikasi lain, otomatisasi yang berjalan dengan akun manusia, atau klien untuk riset. Jika Anda membuat bot, Bot API yang lebih sederhana sudah cukup.

Informasi koneksi

Transport HTTP, transport WebSocket, dan MTProxy belum ada. Jam di perangkat klien harus tepat — nomor pesan MTProto diturunkan dari waktu, jadi jika jamnya meleset jauh, server akan membuang pesan.

Kunci publik server

Saat pertama kali tersambung, klien MTProto mengenkripsi pertukaran auth key dengan kunci publik RSA server. Klien Telegram menyimpan kunci publik Telegram di dalamnya, jadi untuk tersambung ke Pabal Anda harus memasukkan kunci ini sebagai gantinya (atau di sampingnya). Kunci inilah yang mencegah server lain berpura-pura menjadi server 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

Kunci ini dibuat sekali saat server pertama kali menyala dan tidak berubah. Pastikan nilai Loaded RSA key … (fingerprint …) di log server sama dengan fingerprint di atas.

Menyambung dengan Telethon

Berikut contoh masuk ke akun manusia dengan Telethon untuk Python, lalu bertukar pesan. Daftarkan akunnya terlebih dahulu di aplikasi (lihat di bawah).

# pabal_client.py — pip install telethon==1.42.0
# server-key.pem (kunci publik server yang diunduh di atas) di folder yang sama
import asyncio

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

rsa.add_key(open("server-key.pem").read(), old=False)          # kunci publik server Pabal

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # status masuk disimpan di 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("Nomor telepon (+8210…): "))   # masukkan kode sekali saja di awal
    me = await client.get_me()
    print(f"Masuk sebagai: {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

• Pakai Telethon 1.42. Versi inilah yang berbicara dengan layer 216. Versi yang lebih baru mencoba membaca respons dengan layer yang lebih tinggi dan gagal dengan TypeNotFoundError.
• Pendaftaran akun baru diblokir oleh Telethon (sign_up()). Daftar lewat aplikasi, atau panggil auth.signUp secara langsung.
• Status masuk disimpan di berkas pabal.session, jadi lain kali kode tidak ditanyakan lagi. Berkas ini adalah kunci akun Anda, jadi jagalah baik-baik.

Alur masuk

Menerima update

• Real-time: selama koneksi terbuka, server langsung mengirim pesan baru, suntingan, dan penghapusan sebagai updateShortMessage atau updates. Sesi yang mengirim permintaan menerima hasilnya sebagai respons RPC, jadi hal yang sama tidak datang lagi sebagai push.
• pts: setiap perubahan per pengguna diberi nomor urut (pts). Jika ada celah pada pts yang diterima klien, berarti ada sesuatu yang terlewat.
• Menyusul: simpan pts saat ini dengan updates.getState, lalu saat tersambung kembali terima pesan baru, penghapusan, serta pengguna dan grup terkait di antara keduanya dengan updates.getDifference(pts, date, qts). Jika pts milik klien lebih maju daripada server (misalnya data server diatur ulang), yang datang adalah differenceTooLong; muat ulang daftar obrolan.
• Pustaka seperti Telethon mengurus seluruh proses ini secara otomatis.

ID dan peer

Simpan access_hash persis seperti yang diberikan server, lalu pakai kembali (nilainya ikut datang bersama pencarian nama pengguna, daftar obrolan, dan update).

Berkas

• Mengunggah: unggah potongan dengan upload.saveFilePart, lalu rujuk dengan inputFileUploaded…. upload.saveBigFilePart untuk berkas besar belum ada, jadi batas praktisnya 10MB.
• Mengirim: messages.sendMedia dengan inputMediaUploadedPhoto (foto baru) atau inputMediaPhoto (foto yang sudah ada di server). Media lain menghasilkan MEDIA_INVALID.
• Menerima: upload.getFile dengan inputPhotoFileLocation (foto pesan) atau inputPeerPhotoFileLocation (foto profil). Maksimal 1MB per panggilan.
• Foto profil: photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos.
• Foto hanya disimpan dalam satu ukuran, yaitu ukuran aslinya (thumbnail tidak dibuat terpisah).

Cakupan dukungan

Server punya penangan untuk 408 metode layer 216 dan semuanya bisa membaca permintaan, tetapi yang sudah diperiksa sampai tuntas dengan klien sungguhan adalah metode-metode di bawah ini. Sisanya menjawab dengan format yang benar, tetapi isinya bisa kosong atau tidak tercatat.

Sudah dipastikan juga bahwa Telegram Desktop resmi 6.2.6 berfungsi tanpa modifikasi untuk pendaftaran, masuk, obrolan, foto, grup, hingga tersambung ulang. Sekitar 60 metode yang dipanggil aplikasi saat mulai diperiksa format responsnya secara tersendiri.

Error

Error datang sebagai rpc_error standar (error_code + error_message). error_message selalu berbentuk huruf besar, angka, dan garis bawah (PEER_ID_INVALID), dan bila perlu diikuti : keterangan.

Yang belum ada

• Kanal dan supergrup (channels.* menjawab, tetapi tidak tampil dengan benar di aplikasi), obrolan rahasia, panggilan
• Media selain foto, upload.saveBigFilePart, thumbnail
• Verifikasi dua langkah (SRP) — tidak bisa diatur, dan tindakan yang memerlukan verifikasi dua langkah ditolak
• Transport HTTP dan WebSocket, MTProxy, pengiriman msgs_ack, penggantian bad_server_salt
• Pembagian ke beberapa server — satu server menangani semua DC 1–5

Menyambungkan aplikasi Telegram resmi ke Pabal

Aplikasi Telegram menanamkan alamat server dan kunci publik ke dalam dirinya saat dibangun (build). Karena itu, yang perlu diubah bukan layar pengaturan, melainkan kode sumbernya, lalu dibangun ulang. Aplikasi Pabal (Pabal.app) dibuat dengan cara itu. Jika Anda operator server, lihat Instalasi server — menghubungkan aplikasi.