واجهة Pabal البرمجية

واجهة Pabal البرمجية (MTProto)

عندما تبني عميلاً يتصل بالخادم بالطريقة نفسها التي يتصل بها التطبيق: بيانات الاتصال، والمفتاح العام للخادم، ومسار المصادقة، والتحديثات، ونطاق الدعم.

يتحدث تطبيق Pabal مع الخادم عبر MTProto 2.0. استعن بهذا المستند عندما تبني برنامجاً يتصل بالطريقة نفسها — تطبيقاً آخر، أو أتمتةً تعمل بحساب شخص، أو عميلاً لأغراض بحثية. أما إن كنت تبني بوتاً فتكفيك Bot API الأبسط.

بيانات الاتصال

النقل عبر HTTP وعبر WebSocket وMTProxy غير متاحة بعد. يجب أن تكون ساعة جهاز العميل مضبوطة — فأرقام رسائل MTProto مشتقة من الوقت، وإذا كانت الساعة خاطئة كثيراً يتجاهل الخادم الرسائل.

المفتاح العام للخادم

عند الاتصال الأول يشفّر عميل MTProto تبادل مفتاح المصادقة بمفتاح RSA العام للخادم. وعملاء Telegram يحملون في داخلهم المفتاح العام لـ Telegram، لذا يجب لكي يتصلوا بـ Pabal أن تضع هذا المفتاح بدلاً منه (أو معه). فهذا المفتاح هو ما يمنع خادماً آخر من انتحال صفة خادم 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

يُنشأ هذا المفتاح مرة واحدة عند أول تشغيل للخادم، ولا يتغير بعد ذلك. تحقق من أن قيمة Loaded RSA key … (fingerprint …) في سجل الخادم تطابق البصمة أعلاه.

الاتصال باستخدام Telethon

هذا مثال على تسجيل الدخول بحساب شخص وتبادل الرسائل باستخدام Telethon في Python. سجّل الحساب أولاً من التطبيق (انظر أدناه).

# pabal_client.py — pip install telethon==1.42.0
# ضع server-key.pem (المفتاح العام للخادم الذي نزّلته أعلاه) في المجلد نفسه
import asyncio

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

rsa.add_key(open("server-key.pem").read(), old=False)          # المفتاح العام لخادم Pabal

client = TelegramClient("pabal", api_id=1, api_hash="0" * 32)  # يُحفظ تسجيل الدخول في 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("رقم الهاتف (+8210…): "))   # أدخل الرمز مرة واحدة في المرة الأولى
    me = await client.get_me()
    print(f"تم تسجيل الدخول: {me.first_name} (id {me.id})")
    await client.send_message("BotFather", "/help")
    await client.run_until_disconnected()


asyncio.run(main())

• استخدم Telethon 1.42، فهو الإصدار الذي يتحدث بالطبقة 216. أما الإصدارات الأحدث فتحاول قراءة الاستجابات بطبقة أعلى فتفشل بالخطأ TypeNotFoundError.
• تسجيل الحسابات الجديدة معطّل في Telethon (sign_up()). سجّل من التطبيق، أو استدعِ auth.signUp بنفسك.
• يُحفظ تسجيل الدخول في الملف pabal.session، فلا يُطلب منك الرمز في المرات التالية. وهذا الملف مفتاح حسابك، فاحمِه.

مسار تسجيل الدخول

استلام التحديثات

• فورياً: ما دام الاتصال مفتوحاً، يرسل الخادم الرسائل الجديدة والتعديلات وعمليات الحذف مباشرةً على شكل updateShortMessage وupdates. والجلسة التي أرسلت الطلب تستلم النتيجة في استجابة RPC، فلا يصلها الشيء نفسه مرة أخرى عبر الدفع (push).
• pts: لكل مستخدم رقم تسلسلي (pts) يُعطى لكل تغيير. فإذا وجد العميل فجوة في أرقام pts التي استلمها، فقد فاته شيء.
• الاستدراك: احفظ pts الحالي عبر updates.getState، وعند إعادة الاتصال استلم عبر updates.getDifference(pts, date, qts) الرسائل الجديدة وعمليات الحذف التي وقعت في الأثناء، مع المستخدمين والمجموعات المعنيين. وإذا كان pts لدى العميل متقدماً على الخادم (كأن تكون بيانات الخادم قد أُعيدت تهيئتها) يصل differenceTooLong، فأعد تحميل قائمة المحادثات.
• المكتبات مثل Telethon تتولى هذه العملية كلها تلقائياً.

المعرّفات والنظراء

احفظ قيمة access_hash التي يعطيها الخادم كما هي واستخدمها (فهي تأتي مع نتائج البحث عن أسماء المستخدمين وقائمة المحادثات والتحديثات).

الملفات

• الرفع: ارفع الأجزاء عبر upload.saveFilePart ثم أشر إليها بـ inputFileUploaded…. أما upload.saveBigFilePart المخصّصة للملفات الكبيرة فغير متاحة بعد، فالحد الفعلي 10MB.
• الإرسال: استخدم في messages.sendMedia القيمة inputMediaUploadedPhoto (صورة جديدة) أو inputMediaPhoto (صورة موجودة على الخادم). والوسائط الأخرى تعيد MEDIA_INVALID.
• الاستلام: استخدم في upload.getFile القيمة inputPhotoFileLocation (صورة رسالة) أو inputPeerPhotoFileLocation (صورة ملف شخصي). والحد الأقصى 1MB في المرة الواحدة.
• صورة الملف الشخصي: photos.uploadProfilePhoto، وphotos.updateProfilePhoto، وphotos.getUserPhotos، وphotos.deletePhotos.
• تُحفظ الصور بحجم واحد فقط هو الأصل (لا تُنشأ صور مصغّرة منفصلة).

نطاق الدعم

في الخادم معالِجات لـ 408 طرق من الطبقة 216، ويمكنها جميعاً قراءة الطلبات، لكن ما تحققنا منه حتى النهاية بعملاء حقيقيين هو الطرق أدناه. أما البقية فتعيد استجابات بالصيغة الصحيحة، لكن محتواها قد يكون فارغاً أو قد لا يُسجَّل.

وتحققنا كذلك من أن تطبيق Telegram Desktop الرسمي 6.2.6 يعمل دون تعديل في التسجيل وتسجيل الدخول والمحادثات والصور والمجموعات وإعادة الاتصال. أما الطرق التي يستدعيها التطبيق عند بدء تشغيله، وعددها نحو 60 طريقة، فتُفحص صيغة استجاباتها على حدة.

الأخطاء

تصل الأخطاء بالصيغة القياسية rpc_error (error_code + error_message). وتتكوّن error_message دائماً من أحرف كبيرة وأرقام وشرطات سفلية (PEER_ID_INVALID)، وقد يُلحق بها : وصف عند الحاجة.

ما ليس متاحاً بعد

• القنوات والمجموعات الخارقة (تستجيب channels.* لكنها لا تظهر بشكل صحيح في التطبيق)، والمحادثات السرية، والمكالمات
• الوسائط غير الصور، وupload.saveBigFilePart، والصور المصغّرة
• التحقق بخطوتين (SRP) — لا يمكن ضبطه، والعمليات التي تتطلب التحقق بخطوتين تُرفض
• النقل عبر HTTP وWebSocket، وMTProxy، وإرسال msgs_ack، واستبدال bad_server_salt
• التوزيع على عدة خوادم — خادم واحد يتولى مراكز البيانات من 1 إلى 5 كلها

لتوصيل تطبيق Telegram الرسمي بـ Pabal

يضمّن تطبيق Telegram عنوان الخادم والمفتاح العام في داخله عند البناء. لذلك لا يكفي تغييرهما من شاشة الإعدادات، بل يجب تعديل الشيفرة المصدرية وإعادة البناء. وهكذا صُنع تطبيق Pabal ‏(Pabal.app). وإن كنت مشغّل خادم فراجع تثبيت الخادم — توصيل التطبيق.