وثائق المطوّرين
العربية

البدء

نبذة عن Pabal

ما هو Pabal وكيف بُني، وما الذي يعمل الآن وما الذي لا يعمل بعد.

ما هو Pabal

Pabal (파발 擺撥) نظامُ محطات بريدية عرفته كوريا في عهد مملكة جوسون، كان السعاة فيه يبدّلون الخيل في المحطات ويتناوبون على نقل الأخبار العاجلة دون توقف. وPabal.me تطبيق مراسلة يحمل هذا الاسم، متوافق مع Telegram، تشغّله المؤسسات أو المجتمعات على خوادمها الخاصة.

  • تدير الخادم بنفسك. تُحفظ الحسابات والمحادثات والصور كلها على خادم المشغّل وفي قاعدة بياناته (PostgreSQL). واسم برنامج الخادم هو HunsTelegram (Java 21).
  • يتحدث بلغة Telegram نفسها. يتخاطب التطبيق والخادم عبر MTProto 2.0 (الطبقة 216) كما في Telegram، ويتخاطب البوت والخادم عبر HTTP Bot API نفسها التي يستخدمها Telegram. لذلك تتصل التطبيقات والمكتبات والبوتات المبنية لـ Telegram بـ Pabal بمجرد تغيير العنوان.
  • إنه عالم منفصل لا يتصل بـ Telegram. حسابات Pabal موجودة على خادم Pabal فقط، ولا يمكن تبادل الرسائل مع مستخدمي Telegram.

الحديث مع وكلاء الذكاء الاصطناعي: حين تُفعَّل البوتات الصوتية يرد البوت على الرسائل ويستقبل المكالمات أيضاً. يمكنك أن تسأل البوت نفسه برسالة من الكمبيوتر، ثم تتصل به من الهاتف أو من Apple Watch، ويستطيع أي أحد أن ينشئ بوتاً كهذا عبر @BotFather. هذه الميزة قيد الإعداد، وجمعنا ما تستطيع فعله وإلى أين تذهب البيانات في صفحة وكلاء الذكاء الاصطناعي.

كيف بُني

الأشخاص · البرامج المداخل ⁧خادم Pabal (HunsTelegram)⁩ ⁧تطبيق Pabal⁩⁧Pabal.app · تطبيق Telegram⁩ برامج البوتات⁧المكتبات · curl⁩ المتصفحالموقع · الوثائق · الروابط MTProto:8443 · تشفير ذاتي HTTPS :443Caddy (شهادة آلية) البوابةMTProto 2.0 · الطبقة 216 Bot API · webhook/bot<token>/<method> الموقع · الوثائق/ · /docs/ · /اسم_المستخدم الخدمات صناديق الرسائل · المحادثات ⁧التحديثات الفورية (pts)⁩ المجموعات · الصور · الملف الشخصي رموز التسجيل · مفاتيح المصادقة @BotFather · سجل البوتات ⁧صفحة الإدارة (127.0.0.1)⁩ PostgreSQLمخزنالأحداث الملفاتالصور الأصليةdata/media ⁧بوت MTProto⁩ webhook POST (HTTPS)
بنية Pabal — مدخلان، وسجلّ في مكان واحد

شرح المخطط

  • ثلاث مناطق: على اليسار ما يعمل خارج الخادم (التطبيق وبرامج البوتات والمتصفح)، وفي الوسط مدخلا الخادم، وعلى اليمين ما بداخل الخادم. وبرامج البوتات أيضاً تعمل خارج الخادم، على حاسوب المشغّل أو المطوّر.
  • لا يوجد إلا مدخلان: يتصل التطبيق مباشرة عبر منفذ MTProto (8443) (لا حاجة إلى HTTPS لأن MTProto يشفّر بنفسه)، أما الموقع وBot API فيدخلان عبر HTTPS (443).
  • يتصل البوت بأحد طريقين: عادةً عبر Bot API على HTTPS (الخط المتصل)، وإن شئت فعبر MTProto نفسه الذي يستخدمه التطبيق (الخط الأزرق المتقطع). وفي الحالتين هو حساب البوت نفسه وصندوق الرسائل نفسه.
  • الخط الأحمر المتقطع هو السهم الوحيد الذي يسير في الاتجاه المعاكس: عندما يضبط البوت webhook، يرسل الخادم التحديثات الجديدة إلى عنوان HTTPS الخاص ببرنامج البوت. أما البقية فكلها طلبات تدخل من الخارج إلى الخادم.
  • السجلّ في مكان واحد: يمر كل تغيير عبر الخدمات ويُسجَّل في مخزن الأحداث في PostgreSQL، ولا يُحفظ في ملفات سوى الصور الأصلية. والرسائل المرسلة من التطبيق والرسائل التي يرسلها البوت تسلك الطريق نفسه، لذا تنطبق الإشعارات الفورية (push) وقائمة المحادثات واستعادة ما فات عند إعادة الاتصال على الجميع بالطريقة نفسها.

يمثّل المخطط أعلاه طريق الرسائل. وعلى الخادم الذي تُفعَّل فيه البوتات الصوتية تُضاف مداخل للمكالمات — ترحيل المكالمات (UDP 3478) ونقطة دخول الصوت لساعة Apple Watch (WSS). ورسمنا هذا الطريق في صفحة وكلاء الذكاء الاصطناعي.

ما يعمل الآن، وما لا يعمل بعد

الميزةالحالةملاحظات
التسجيل وتسجيل الدخول (رقم الهاتف + رمز)يعمليختار المشغّل إيصال الرمز عبر SMS أو البريد الإلكتروني أو عن طريق المسؤول
المحادثات الفردية، والاستلام الفوري، والأجهزة المتعددةيعملالجهاز الذي كان مطفأً يستدرك ما فاته عند تشغيله من جديد
تعديل الرسائل وحذفهايعملينعكس فوراً على شاشة الطرف الآخر أيضاً
المجموعات العادية (الإنشاء، وإضافة الأعضاء، وإخراجهم، والاسم)يعمليُضاف الأعضاء مباشرة من معلومات المجموعة
إرسال الصور، وصورة الملف الشخصييعملتُحفظ بحجم واحد فقط هو الحجم الأصلي
إرسال الملفات (بجميع الصيغ)يعمليُحفَظ الاسم والصيغة كما هما. وما تجاوز 10MB يُرفع عبر upload.saveBigFilePart، والحدّ الافتراضي 2GB
البوتات — @BotFather، وHTTP Bot API، وwebhook، وبوتات MTProtoيعملالأزرار، والاستدعاءات (callbacks)، وقائمة الأوامر، والصور، والملفات، والمجموعات
صفحة الإدارة، وإعدادات التشغيليعملمتاحة فقط على العنوان 127.0.0.1 في الخادم
الموقع بعشر لغات، وصفحات روابط أسماء المستخدمين والدعواتيعملووثائق المطوّرين أيضاً بعشر لغات
المكالمات الفرديةيعملنجاح المكالمات بين شبكات مختلفة يتوقف على إعداد خادم الترحيل (TURN)
الإشعارات الفورية — Androidيعملإشعارات الرسائل ورنين المكالمات حتى لو كان التطبيق مغلقاً. ويجب أن يُعدّ المشغّل Firebase (تثبيت الخادم)
الإشعارات — macOS وWindowsيعملتُعرض في إشعارات الحاسوب ما دام التطبيق يعمل (دون إشعارات فورية)
عرض الأجهزة المسجَّل دخولها وتسجيل خروجها (الأجهزة في الإعدادات)يعمل — لم يُتحقق منه بعد بالتطبيقات الحقيقيةالجهاز الذي سُجِّل دخوله قبل أقل من 24 ساعة لا يستطيع تسجيل خروج الأجهزة الأخرى (ولا تعرض تطبيقات Android وسطح المكتب أي تنبيه عندها). تحقّقنا منه باختبارات الخادم، ولم يُتحقق منه بعد من أوله إلى آخره بالتطبيقات الحقيقية — استخدام التطبيق — حماية حسابك
تصدير البيانات (تطبيق سطح المكتب)يعمل — لم يُتحقق منه بعد بالتطبيق الحقيقيالمحادثات والصور والملفات ومعلومات الحساب. ثلاث مرات بدء في اليوم على الأكثر، وإعادة تشغيل الخادم تعني البدء من جديد. ولا توجد بعدُ مهلة الانتظار التي في Telegram ولا الموافقة من جهاز آخر ولا سجل عمليات التصدير. اختُبر بالطلبات التي يرسلها تطبيق سطح المكتب وبترتيبها نفسه، ولم يُتحقق منه بعد من أوله إلى آخره بالتطبيق الحقيقي
تغيير رقم الهاتفمعطّل افتراضياًإذا فعّله المشغّل يصل رمز برسالة SMS إلى الرقم الجديد (فقط في الخوادم التي ضُبطت فيها رسائل SMS) — الإدارة والإعدادات — رموز التسجيل وتسجيل الدخول
القنوات، والمجموعات الخارقةليس بعدقد لا تظهر بشكل صحيح في التطبيق
الفيديو والرسائل الصوتيةليس بعديمكن إرسالها بوصفها ملفات، لكنها لا تُشغَّل داخل التطبيق
الألبومات (عدة عناصر في حزمة واحدة)ليس بعدإذا أرسلت عدة عناصر دفعةً واحدة فإنها تصل كلها، لكنها تظهر منفصلة واحداً تلو الآخر لا مجمّعة
النص المنسّق (غامق، مائل)، وparse_mode في البوتاتليس بعديُرسل النص كما هو. أما الأوامر والإشارات (mentions) والروابط والوسوم فتُميَّز تلقائياً
المكالمات الجماعية، والمحادثات السريةليس بعد
التحقق بخطوتين (كلمة المرور السحابية)ليس بعدأي محاولة لتفعيله تُرفض
تطبيق iPhoneقيد الإعدادقُدِّم الإصدار الأول (1.0) لمراجعة App Store (2026-09-23). ولا يتضمن الإصدار 1.0 إشعارات فورية، فلا يستلم الرسائل إلا ما دام التطبيق مفتوحاً. والإصدار 1.1 الذي يتضمن الإشعارات الفورية قيد الاختبار الداخلي (TestFlight)
الانضمام إلى مجموعة عبر رابط دعوةليس بعديُنشأ الرابط، لكن النقر عليه لا يضيفك عضواً
الوضع المضمّن (@bot كلمات البحث)، والمدفوعات، والألعابليس بعد
البوتات الصوتية (تتصل ببوت فيرد عليك الذكاء الاصطناعي)قيد الإعدادلا تعمل إلا بعد توفّر الخادم والوثائق القانونية وتطبيق يتضمن نافذة التأكيد. وهي معطّلة على pabal.me، وتُختبر على خادم التطوير — البوتات الصوتية
تطبيق Apple Watch (مكالمات البوتات الصوتية)قيد الإعدادللاختبار الداخلي فقط (TestFlight). تتصل بالبوت الصوتي من الساعة دون iPhone — استخدام التطبيق — Apple Watch
الاحتفاظ بالمحادثة (حفظ محادثة المكالمة نصاً في محادثتي)قيد الإعدادقبل المراجعة القانونية لنصوص نافذة التأكيد — استخدام التطبيق — البوتات الصوتية
المكالمات من البوتات (بوت أذِنت له يتصل بك بصوت بالذكاء الاصطناعي)معطّلةبانتظار المراجعة القانونية، ولا يوجد بعدُ إصدار من التطبيق فيه نافذة الإذن — استخدام التطبيق — السماح لبوت بالاتصال بك

العلاقة مع Telegram

Pabal خادم مستقل يتّبع البروتوكول العلني الذي نشرته Telegram. ولا علاقة له بشركة Telegram، ولا يتصل بخوادمها.

  • ما هو متوافق: MTProto 2.0 (أنواع النقل الأربعة، والمصافحة، وربط المفاتيح المؤقتة)، وصيغ الطلبات والاستجابات في الطبقة 216، وصيغة العناوين والطلبات والاستجابات والأخطاء في HTTP Bot API. وقد تحقّقنا من ذلك بتوصيل تطبيق Telegram Desktop الرسمي 6.2.6 دون تعديل (بتغيير عنوان الخادم والمفتاح العام فقط).
  • ما هو مختلف: الحسابات والبيانات منفصلة لكل خادم. ومعرّفات المستخدمين والرسائل والملفات لا معنى لها إلا داخل هذا الخادم. ولا يمكنك استخدام الرمز المميّز (token) للبوت الذي كنت تستخدمه في Telegram، بل عليك الحصول على رمز جديد من @BotFather في Pabal.

تبدأ الروابط التي ينشئها التطبيق والخادم بـ https://pabal.me/. وعند فتح الرابط في المتصفح تظهر صفحة صغيرة تفتح التطبيق.

الرابطالمعنىالعنوان الذي يُفتح في التطبيق
pabal.me/<اسم المستخدم>فتح المحادثة مع شخص أو بوتtg://resolve?domain=<اسم المستخدم>
pabal.me/+<رمز الدعوة>رابط دعوة إلى مجموعة (يفتح التطبيق، لكن الانضمام عبر الرابط لا يعمل بعد)tg://join?invite=<رمز الدعوة>
pabal.me/joinchat/<رمز الدعوة>رابط دعوة بالصيغة القديمة (المعنى نفسه)tg://join?invite=<رمز الدعوة>

اسم المستخدم من 5 إلى 32 حرفاً من الأحرف اللاتينية والأرقام والشرطة السفلية، ويبدأ بحرف لاتيني (وينتهي اسم مستخدم البوت بـ bot). والأسماء المطابقة لمسارات يستخدمها الموقع، مثل docs وadmin وhealth، لا تُفتح كروابط.

نموذج الأمان

  • التطبيق ↔ الخادم: الاتصال مشفّر بـ MTProto 2.0. ويُبنى التطبيق ومفتاح RSA العام للخادم مضمّن فيه، فلا يستطيع خادم آخر أن ينتحل صفة خادم Pabal. والمحادثات مثل «المحادثات السحابية» في Telegram، لذلك يستطيع الخادم قراءة محتواها (فهي ليست مشفّرة من طرف إلى طرف). ولهذا يجب أن يشغّل الخادمَ شخصٌ جدير بالثقة.
  • البوت ↔ الخادم: لا تُتاح Bot API إلا عبر HTTPS. والرمز المميّز للبوت هو كلمة مروره — فإذا تسرّب فغيّره بالأمر /revoke لدى @BotFather. عندها يُلغى الرمز السابق وتُقطع فوراً الاتصالات التي كانت قائمة به.
  • الخادم ← webhook: لا يرسل الخادم طلباته إلا إلى عناوين webhook عامة تستخدم HTTPS. ويرفض العناوين الداخلية مثل الشبكات الخاصة وعنوان الاسترجاع (loopback) وخدمة البيانات الوصفية السحابية (metadata). ويستطيع البوت أن يتحقق عبر secret_token من أن الطلب جاء فعلاً من خادم Pabal.
  • الخادم ← إشعارات Android: تمرّ الإشعارات الفورية عبر خدمة Firebase Cloud Messaging (FCM) من Google. ويشفّر الخادم محتوى الإشعار (اسم المرسل ومعاينة الرسالة) بمفتاح لا يملكه إلا ذلك الهاتف قبل إرساله، فلا تستطيع Google قراءته، ولا ترى إلا معلومات التسليم مثل الرمز المميّز للجهاز ووقت الإرسال. ويستطيع المشغّل أيضاً أن يستبعد محتوى الرسائل من الإشعارات تماماً.
  • الخادم ← إشعارات iPhone: تمرّ الإشعارات الفورية في iPhone عبر خدمة APNs من Apple. وكما في Android، لا ترى Apple من النص الظاهر إلا «لديك إشعار جديد»، أما المرسل والمحتوى فمشفّران بمفتاح لا يملكه إلا ذلك الجهاز ويُفك تشفيرهما داخل الهاتف. ويسري ذلك بدءاً من بناء التطبيق الذي يتضمن الإشعارات الفورية (1.1).
  • مكالمات البوتات الصوتية (قيد الإعداد): بخلاف المكالمات بين الأشخاص، ليست المكالمة مع البوت مشفّرة من طرف إلى طرف. فبوابة الصوت في Pabal تفك تشفير الصوت وتسلّمه إلى نموذج الذكاء الاصطناعي، وإذا استُخدم المحرّك الافتراضي يذهب صوت المكالمة إلى Google في الولايات المتحدة (Google Cloud us-central1). أما ما يستطيع المشغّل أن يقرّره — تشغيل الخادم بنفسه، ومفتاح النموذج الخاص بمالك البوت، ووضع الصوت الخام، ومفاتيح المشغّل — ففي وكلاء الذكاء الاصطناعي — ما نستطيع أن نقرّره.
  • الإدارة: لا تُفتح صفحة الإدارة إلا على الخادم نفسه (127.0.0.1)، ولا يمكن رؤية البيانات إلا بوجود رمز مميّز. ويدخل المشغّل إليها عبر نفق SSH.
  • التخزين: مفاتيح المصادقة محفوظة في قاعدة البيانات كما هي، لأن الخادم يحتاج إليها لفك التشفير. لذلك يجب حماية قاعدة البيانات والنسخ الاحتياطية بقدر ما يُحمى مفتاح RSA الخاص بالخادم.

المصطلحات

المصطلحالمعنى
MTProtoبروتوكول التشفير بين التطبيق والخادم الذي أنشأته Telegram. ويستخدم Pabal الإصدار 2.0.
الطبقة (layer)إصدار صيغ الطلبات والاستجابات التي تُتبادل فوق MTProto. وطبقة Pabal هي 216.
مفتاح المصادقة (auth key)سرّ بطول 2048 بت ينشئه التطبيق مع الخادم عند أول اتصال. ويرتبط تسجيل الدخول بهذا المفتاح.
DCرقم مركز البيانات في Telegram. في Pabal يتولى خادم واحد مراكز البيانات من 1 إلى 5 كلها.
التحديثات، ptsتغييرات مثل الرسائل الجديدة والتعديلات والحذف. وpts هو الرقم التسلسلي لتغييرات كل مستخدم، وبه يعرف الجهاز الذي انقطع اتصاله ما فاته.
الإشعارات الفورية (push)تنبيه يوقظ الهاتف حين يكون التطبيق مغلقاً أو في الخلفية. ويرسلها Pabal إلى تطبيق Android عبر Google FCM، وإلى تطبيق iPhone عبر Apple APNs.
النظير (peer)الطرف الآخر في المحادثة — شخص أو بوت أو مجموعة.
الرمز المميّز للبوت (token)سلسلة بالشكل <bot ID>:<secret>، أي معرّف البوت ثم سرّه. تُوضع في عنوان Bot API لإثبات هوية البوت.
Webhookطريقة يرسل فيها الخادم التحديثات الجديدة إلى عنوان HTTPS الخاص بالبوت، بدلاً من أن يأتي البوت لجلبها.
وكيل الذكاء الاصطناعي (AI agent)بوت يرد على الرسائل ويستقبل المكالمات أيضاً. وهو في Pabal البوت الذي فُعّل فيه الصوت (قيد الإعداد).
البوت الصوتيبوت يمكن للناس الاتصال به. ولا يرد على المكالمة شيفرة مالك البوت، بل نموذج صوتي بالذكاء الاصطناعي.
بوابة الصوتمكوّن في Pabal (pabal-voice) يصبح طرف المكالمة بدلاً من البوت، فيفك تشفير الصوت ويتبادله مع نموذج الذكاء الاصطناعي. وهي غير بوابة MTProto التي يتصل بها التطبيق.
وضع الصوت الخامطريقة عمل للبوت الصوتي يستلم فيها خادم مطوّر البوت صوت المكالمة مباشرة بدلاً من نموذج الذكاء الاصطناعي.
الاحتفاظ بالمحادثةإذا اختاره المتصل، تُحفظ محادثة المكالمة بعد انتهائها نصاً في محادثته هو فقط. ولا تصل إلى البوت ولا إلى مالك البوت.