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

Menghubungkan lewat 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; saat tersambung kembali, ambil pesan baru dan penghapusan yang terjadi selama terputus, beserta pengguna dan grup terkait, 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.
• Notifikasi push — Android: aplikasi Android yang tidak tersambung dibangunkan oleh push Firebase. Setelah aplikasi mendaftar dengan account.registerDevice (token_type 2 = token FCM, secret = kunci perangkat 256 byte), server mengenkripsi pesan dan panggilan baru dengan kunci perangkat itu lalu mengirimnya lewat FCM, dan aplikasi yang terbangun menyusul dengan updates.getDifference. Push hanya bisa sampai ke aplikasi yang dibangun dengan project Firebase milik operator server.
• Notifikasi push — iPhone: aplikasi iPhone mendaftarkan dua hal dengan permintaan yang sama — token_type 1 (token notifikasi APNs) dan 9 (token VoIP PushKit); secret untuk keduanya adalah kunci perangkat 256 byte milik akun itu. Pesan baru dikirim sebagai notifikasi APNs: teks luar yang bisa dilihat Apple hanyalah nama aplikasi dan kalimat tanpa isi seperti "Ada notifikasi baru", sedangkan pesannya dienkripsi dengan kunci perangkat dan dimuat di p, lalu ekstensi notifikasi aplikasi (Notification Service Extension) membukanya dan menampilkannya. Panggilan memunculkan layar panggilan CallKit lewat push VoIP (mulai dari build yang VoIP-nya sudah dinyalakan operator; sebelum itu sebagai notifikasi), dan apa yang dibaca atau dihapus di perangkat lain diberitahukan lewat push latar belakang. Push hanya bisa sampai ke aplikasi yang ditandatangani oleh tim yang sama dengan pemilik kunci APNs operator server dan memiliki bundle ID yang sama. token_type lainnya hanya dijawab boolTrue tanpa dikirimi apa pun.
• 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 (maksimal 512KB per potongan, hingga 4.000 potongan) dengan upload.saveFilePart, lalu rujuk dengan inputFileUploaded…. Berkas yang lebih dari 10MB diunggah dengan upload.saveBigFilePart — karena jumlah potongannya diberitahukan lebih dulu, berkas yang ukurannya tidak diterima server ditolak dengan FILE_TOO_BIG sebelum semuanya terkirim. Potongan langsung ditulis ke disk begitu tiba, lalu disatukan ketika ada pesan yang merujuk berkas itu.
• Mengirim: messages.sendMedia dengan inputMediaUploadedPhoto (foto baru), inputMediaPhoto (foto yang sudah ada di server), inputMediaUploadedDocument (berkas baru), atau inputMediaDocument (berkas yang sudah ada di server). Media lainnya menghasilkan MEDIA_INVALID. Anda juga bisa mengunggah lebih dulu tanpa mengirimnya dengan messages.uploadMedia (media yang dikembalikannya bisa Anda kirim apa adanya nanti), sedangkan messages.sendMultiMedia diterima tetapi kirimannya datang satu per satu dan tidak disatukan (tanpa grouped_id).
• Menerima: upload.getFile dengan inputPhotoFileLocation (foto pesan), inputDocumentFileLocation (berkas pesan), atau inputPeerPhotoFileLocation (foto profil). Maksimal 1MB per panggilan. Saat menerima pun berkas tidak dimuat seluruhnya ke memori; hanya bagian yang diminta yang dibaca.
• Foto profil: photos.uploadProfilePhoto, photos.updateProfilePhoto, photos.getUserPhotos, photos.deletePhotos.
• Foto hanya disimpan dalam satu ukuran, yaitu ukuran aslinya (thumbnail tidak dibuat terpisah). Berkas dibiarkan apa adanya tanpa disentuh, dan documentAttribute* yang dilampirkan pengirim diteruskan byte demi byte ke penerima — server meneruskannya begitu saja tanpa perlu memahami durasi video atau bentuk gelombang suara.

Cakupan dukungan

Server punya penangan untuk 469 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.

Yang ditambahkan sesudahnya — daftar perangkat dan mengeluarkannya (account.getAuthorizations, account.resetAuthorization, auth.resetAuthorizations), ekspor data aplikasi desktop (account.initTakeoutSession, invokeWithTakeout, invokeWithMessagesRange, account.finishTakeoutSession — tiga kali mulai per hari per akun, lebih dari itu 420 TAKEOUT_INIT_DELAY_n), dan mengganti nomor (account.sendChangePhoneCode, account.changePhone — 400 PHONE_CHANGE_DISABLED selama operator belum menyalakannya, BOT_METHOD_INVALID untuk bot) — sudah dipastikan dengan uji server; pemeriksaan ujung ke ujung dengan aplikasi sungguhan belum dilakukan.

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.

API jam tangan

/api/watch/v1/ di server adalah pintu masuk JSON lewat HTTPS khusus untuk aplikasi Pabal di Apple Watch. Pintu ini dibuat terpisah karena jam tangan tidak bisa memakai MTProto, dan ini bukan spesifikasi publik serta masih disiapkan, jadi bisa berubah tanpa pemberitahuan. Untuk membuat program yang tersambung ke Pabal, gunakan MTProto di halaman ini. Operator server silakan membaca Instalasi server — pintu masuk Apple Watch.

Yang belum ada

• Kanal dan supergrup (channels.* menjawab, tetapi tidak tampil dengan benar di aplikasi), obrolan rahasia, panggilan grup
• Pesan video dan suara yang diputar di dalam aplikasi, album yang ditampilkan sebagai satu kesatuan (grouped_id), stiker, thumbnail (berkas hanya aslinya)
• Verifikasi dua langkah (SRP) — tidak bisa diatur, dan tindakan yang memerlukan verifikasi dua langkah ditolak
• Transport HTTP dan WebSocket, MTProxy, pengiriman msgs_ack, rotasi berkala salt server (salt yang salah dijawab dengan 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.