telegram-bot-dumper

تفريغ سهل لكل محتويات بوت تيليجرام.

المدخل: رمز البوت فقط.

المخرج: اسم البوت ومعلوماته، كل سجل نصوص المحادثات والوسائط، معلومات مستخدمي البوت وصورهم.

---

هذا تنفيذ بلغة Python.

🚀 نسخة Golang السريعة من ScBoln.

عارض الويب

واجهة متصفح شبيهة بـ Telegram-Web لتفريغ البيانات: قائمة المحادثات، سجل الرسائل الكامل مع الوسائط المضمّنة، ملفات المستخدمين مع عارض صور دوّار، وبحث شامل عبر كل المحادثات دفعة واحدة. الوضع المباشر مدعوم: يشغّل أداة التفريغ في الخلفية ويبثّ الرسائل الجديدة إلى المتصفح في الوقت الفعلي.

حالة الاستخدام — اختبار اختراق لرمز بوت مسرّب. تظهر رموز بوتات تيليجرام باستمرار أثناء أي مهمة — مضمّنة بشكل صلب في تطبيق جوال/سطح مكتب، أو مُودعة في مستودع، أو موجودة في سجل CI، أو ملف إعدادات، أو حزمة من جهة العميل. بمفرده يبدو الرمز كاكتشاف منخفض الخطورة؛ لكن تحميله هنا يُظهر مدى التأثير الحقيقي. بالنسبة لبوت داخلي (مكتب دعم، مساعد IT/DevOps، مساعد ذكاء اصطناعي) فإن ذلك يعني كل محادثة موظف معه — أسماء مضيفين داخلية، ملفات تعريف VPN، بيانات اعتماد، وتفاصيل البنية التحتية — قابلة للتصفح والبحث، ما يتيح لك تحديد نطاق التأثير وتوثيق الاكتشاف في تقريرك.

التشغيل من صورة جاهزة (Docker Hub)

docker run --rm -p 8010:8010 -v "$PWD:/data" soxoj/telegram-bot-dumper-web

أو البناء محليًا

docker compose up --build      # builds and serves on http://127.0.0.1:8010

أو بدون Docker

pip install -r requirements.txt
python webapp/server.py        # serves the current directory's dumps on :8010

افتح http://127.0.0.1:8010 والصق رمز بوت لاختيار مجلد التفريغ الخاص به. العرض للقراءة فقط بدون مصادقة، محلي، ولا يحتاج بيانات اعتماد API. الوضع المباشر يحتاج إضافةً إلى ذلك API_ID/API_HASH من my.telegram.org، تُمرَّر عبر البيئة — ولا تُضمَّن أبدًا في الصورة:

# one-off container
docker run --rm -p 8010:8010 -v "$PWD:/data" \
  -e API_ID=123456 -e API_HASH=abc... soxoj/telegram-bot-dumper-web

# or with docker compose: put them in a local .env (see .env.example)
cp .env.example .env && $EDITOR .env && docker compose up

متغيّرات البيئة PORT وHOST تتجاوز القيم الافتراضية (8010، 127.0.0.1).

الميزات

• تفريغ رسائل البوت مع محتوى الوسائط عبر التنقل بين معرّفات الرسائل تصاعديًا (افتراضيًا) أو تنازليًا (--down / --start-from-id).
• وضع الاستماع المباشر (--listen-only): استقبال الرسائل الجديدة في الوقت الفعلي وعرض خيار تفريغ السجل تنازليًا من أول معرّف يُرصد.
• استخراج معلومات المستخدم لكل من الرسائل الواردة و ردود البوت الصادرة.
• أوضاع خفيفة لسرد المستخدمين بسرعة: تخطّي الوسائط، تخطّي سجل النصوص لكل محادثة، وكتابة المستخدمين في ملف CSV واحد.
• رسائل المجموعات / المجموعات الفائقة تُوسَم بـ [from:USER][group:CHAT]. الرسائل المباشرة الصادرة من البوت تُوسَم بـ [to:USER].
• مراقبة المجموعات: إذا أُضيف البوت إلى مجموعة/مجموعة فائقة وكان وضع الخصوصية معطّلًا، فسيستقبل البوت كل رسائل المجموعة — وليس الأوامر والردود فقط — وسيقوم --listen-only بتفريغها في الوقت الفعلي. مع تفعيل وضع الخصوصية (الافتراضي) لا يرى البوت سوى الأوامر والإشارات والردود.

المتطلبات

• Python >= 3.6
• Telethon (راجع requirements.txt للإصدار المثبّت)
• تسجيل تطبيق تيليجرام للحصول على API_ID وAPI_HASH

الاستخدام كأداة سطر أوامر

pip install -r requirements.txt

# Telegram API credentials from https://my.telegram.org (read from the environment)
export API_ID=123456
export API_HASH=abc...

البدء السريع — تفريغ كامل (السلوك الافتراضي)

يتنقل بين المعرّفات 1..∞ تصاعديًا على دفعات من 200، نزّلًا لكل رسالة وكل وسائط وكل صور ملفات المستخدمين. افتراضيًا، تستمر أداة التفريغ في الاستماع للرسائل الواردة الجديدة بعد انتهاء التفريغ. للخروج فورًا بعد تفريغ السجل (مثالي للسكربتات ومهام cron)، مرّر --no-listen.

./dumper.py --token 12345678:ABCe2rPVteUWZ7wLeCqCb3CH3ilUY_fLabc

التفريغ تنازليًا من أحدث رسالة

بالنسبة لبوت نشط، يصطدم التنقل التصاعدي بامتداد طويل من المعرّفات القديمة المحذوفة (المحذوفة/المنتهية) ويستسلم. التنقل تنازليًا من أحدث معرّف أكثر إنتاجية بكثير. يقوم --down بفحص الحد الأعلى تلقائيًا (قوى العشرة حتى 10⁹) ويبدأ من أعلى معرّف غير فارغ يجده:

./dumper.py --token TOKEN --down

ملاحظة. لا يحتفظ تيليجرام بسجل رسائل البوت إلى الأبد. عمليًا، تبقى فقط آخر بضع مئات الآلاف من الرسائل قابلة للوصول — في اختباراتنا كشف بوت مزدحم عن آخر 500K رسالة تقريبًا قبل أن يبدأ messages.getMessages بإرجاع MessageEmpty فقط للمعرّفات الأقدم. إذا كان بوتك قد عالج تاريخيًا حركة أكثر من ذلك، فالسجل الأقدم مفقود ببساطة على الخادم ولن يستعيده أي خيار.

إذا كنت تعرف بالفعل معرّف رسالة حديثًا (مثلًا واحدًا رأيته في الوقت الفعلي)، يمكنك تخطّي الفحص والبدء منه بالضبط:

./dumper.py --token TOKEN --start-from-id 11922524

وضع الاستماع

لا تفريغ لأي شيء؛ فقط راقب ما يصل. عند أول رسالة واردة سيعرض السكربت بدء تفريغ تنازلي من ذلك المعرّف:

./dumper.py --token TOKEN --listen-only

سرد المستخدمين الخفيف (CSV، بدون وسائط، بدون سجل لكل محادثة)

مفيد عندما تحتاج فقط إلى قائمة بمن تحدّث مع البوت — بدون ملفات zip، بدون صور jpeg، بدون *_history.txt لكل محادثة.

./dumper.py --token TOKEN --down --users-csv --no-photos --no-media --no-history

المخرج: <bot_id>/users.csv بأعمدة id, username, first_name, last_name, phone, lang_code, bot, premium, verified, scam, fake.

الاستئناف بعد انهيار / FloodWait

يطبع التنقل التنازلي Requesting message ids X..Y ... لكل دفعة. إذا قوطعت الجلسة، أعد التشغيل من آخر حد أدنى مطبوع:

./dumper.py --token TOKEN --start-from-id <Y>

ضبط حجم الدفعة

دفعات أصغر → تغذية راجعة أسرع في السجل ونافذة استرداد أقصر بعد FloodWait. دفعات أكبر → جولات ذهاب وإياب أقل عند مسح نطاقات معرّفات متباعدة / محذوفة. القيم حتى 1000 تعمل جيدًا عمليًا.

./dumper.py --token TOKEN --down --batch-size 50
./dumper.py --token TOKEN --down --batch-size 500
./dumper.py --token TOKEN --down --batch-size 1000

خيارات أخرى

الخيار	التأثير
--lookahead N	بعد دفعة فارغة بالكامل، استمر في مسح N دفعات إضافية قبل الاستسلام. مفيد عندما تكون المعرّفات متباعدة.
--no-photos	تخطّي تنزيل صور ملفات المستخدمين (الصور الرمزية).
--no-media	تخطّي تنزيل الصور والمستندات داخل الرسائل؛ لا تزال البيانات الوصفية تُكتب في سجل النصوص.
--no-history	لا تكتب <chat_id>_history.txt لكل محادثة. اجمعها مع --users-csv لأخفّ تشغيل ممكن.
--users-csv	اكتب المستخدمين في ملف <bot_id>/users.csv واحد بدلًا من مجلدات <user_id>/<user_id>.json.
--tor	التوجيه عبر وكيل Tor SOCKS5 محلي على 127.0.0.1:9050 (تجاوز حجب تيليجرام).

شغّل ./dumper.py --help للقائمة الكاملة.

المشكلات المعروفة حاليًا

1. يخرج البوت قبل تفريغ السجل بالكامل. إذا حذف المستخدمون بعض الرسائل، فقد تعود دفعة فارغة بالكامل وقد يتوقف السكربت مبكرًا جدًا. إضافةً إلى ذلك، إذا عالج البوت كمية ضخمة جدًا من الحركة، فلن تُرجع خوادم تيليجرام الرسائل القديمة ببساطة — فقد حُذفت ولن يستعيدها أي خيار. بالنسبة لسجل متباعد لكنه موجود، ارفع --lookahead لمواصلة المسح بعد الامتدادات الفارغة:

   # check additionally 5*200 = 1000 ids
   ./dumper.py --token TOKEN --lookahead 5
   

   أو استخدم --down فقط، فهو أقل تأثرًا بكثير بالفجوات في المعرّفات القديمة.

2. لم يُفرَّغ السجل لمحادثات المجموعات (المجموعات الأساسية، المجموعات الفائقة). يُرجع messages.getMessages سجل الرسائل المباشرة للبوت فقط؛ سجل المجموعات الفائقة يتطلب استدعاءات لكل قناة لا تستطيع البوتات عادةً تنفيذها. لا تزال رسائل المجموعات تُلتقط مباشرةً في وضع --listen-only إذا كانت خصوصية المجموعة معطّلة (راجع الميزات).

الاختبار

اختبارات وحدة دون اتصال (بدون شبكة، بدون رمز):

pip install -r test-requirements.txt
pytest tests/ --ignore=tests/bot_test.py

اختبار تكاملي مقابل بوت حقيقي (يتطلب رمز بوت صالح):