بوت تيليجرام للتنبيهات: خلّي سيرفرك يكلّمك على موبايلك ببايثون

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

ابعت تنبيهات سيرفرك على تيليجرام ببوت بايثون من الصفر

في آخر الشرح ده هيكون عندك بوت يبعتلك رسالة على موبايلك أول ما القرص يمتلئ أو الخدمة تقع، من غير ما تفتح لوحة مراقبة ولا تفضل مراجع الإيميل. الرسالة بتوصل كإشعار فوري، وغالبًا في أقل من ثانيتين.

المشكلة باختصار

الطريقة الشائعة إنك تفتح لوحة المراقبة كل شوية وتبص بعينك على الرسوم. الطريقة دي بتفشل بالليل ونهاية الأسبوع، لأنك مش قاعد قدام الشاشة. النتيجة إن القرص بيمتلئ الساعة 2 الفجر، والتطبيق بيقع، وإنت بتكتشف الموضوع الصبح من شكوى مستخدم.

بدل ما إنت تروح تسأل السيرفر، خلّي السيرفر هو اللي يجيلك. تيليجرام بيوفّر واجهة برمجية مجانية اسمها Bot API تبعت بيها رسالة بسطر واحد. ده اللي بنبنيه هنا.

الطريقة القديمة اللي بنستبدلها

اللوحات زي الصورة دي مفيدة للتحقيق بعد وقوع المشكلة، لكنها ضعيفة كنظام إنذار. هي بتنتظرك تبص. التنبيه الجيد بيعمل العكس: بيقاطعك هو لما يحصل شيء يستاهل، ويسيبك في حالك لما كل حاجة تمام.

مفهومان لازم تفهمهما الأول

قبل الكود، فيه كلمتين هتتكرروا: التوكن (Token) وchat_id. خليني أقرّبهم بمثال، بعدها بالتعريف الدقيق.

تخيّل إن عندك صندوق بريد خاص. التوكن هو مفتاح الصندوق: أي حد معاه المفتاح يقدر يبعت باسمك، فخليه سر. وchat_id هو عنوان البيت اللي الرسالة هتتحط في صندوقه؛ من غيره تيليجرام مش عارف يوصّل لمين.

بالتعريف الدقيق: التوكن سلسلة نصية يصدرها BotFather وتُستخدم لتوثيق كل طلب ترسله لواجهة Bot API، وشكلها رقم البوت متبوعًا بنقطتين ثم تجزئة عشوائية. و chat_id معرّف رقمي للمحادثة (سواء كانت أنت شخصيًا، أو مجموعة، أو قناة) يحدّد وجهة التسليم.

الخطوات: من الصفر لأول تنبيه

1. أنشئ البوت. افتح محادثة مع @BotFather في تيليجرام، ابعت /newbot، اختر اسمًا ومعرّفًا ينتهي بـ bot. هيرجّعلك سطر التوكن. انسخه واحتفظ به.
2. ابدأ محادثة مع بوتك. افتح رابط البوت وابعتله أي كلمة مثل /start. الخطوة دي ضرورية عشان تيليجرام يعرف يسمحلك بالتسليم.
3. اجلب chat_id. شغّل الأمر ده بعد ما تبعت الكلمة، وهتلاقي رقمك جوه chat.id:

# استبدل TOKEN بالتوكن بتاعك
curl -s "https://api.telegram.org/botTOKEN/getUpdates"
# دوّر في النتيجة على: "chat":{"id":987654321, ...}

1. ابعت أول رسالة اختبار. جرّب الأمر ده، والمفروض توصلك رسالة في ثوانٍ:

curl -s -X POST "https://api.telegram.org/botTOKEN/sendMessage" \
     -d chat_id=987654321 \
     -d text="السيرفر شغّال. ده أول تنبيه من البوت."

لو وصلت الرسالة، يبقى النصف الصعب خلص. الباقي مجرد تغليف الكلام ده في بايثون وربطه بفحص حقيقي.

دالة تنبيه قابلة لإعادة الاستخدام

هنعمل دالة واحدة send_alert نناديها من أي سكربت. الافتراض إن السيرفر عنده اتصال HTTPS خارجي بـ api.telegram.org؛ لو مقفول، الجزء ده مش هيشتغل.

import requests

BOT_TOKEN = "123456:ABC-ضع-توكنك-هنا"   # من BotFather
CHAT_ID   = "987654321"                  # رقم محادثتك

def send_alert(text: str) -> None:
    url = f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage"
    data = {"chat_id": CHAT_ID, "text": text}
    r = requests.post(url, data=data, timeout=10)
    r.raise_for_status()   # يرمي خطأ لو التوكن غلط أو الشبكة وقعت

لو مش عايز تنصّب مكتبة، تقدر تستخدم urllib الموجودة أصلًا مع بايثون، بس requests أوضح للمبتدئ. لتنصيبها: pip install requests.

اربطها بفحص حقيقي: امتلاء القرص

التنبيه من غير سبب واقعي بلا فائدة. خلينا نفحص مساحة القرص، ونبعت رسالة بس لو تجاوزت 90%.

import shutil

def disk_usage_percent(path: str = "/") -> float:
    total, used, free = shutil.disk_usage(path)
    return used / total * 100

pct = disk_usage_percent("/")
if pct >= 90:
    send_alert(f"تنبيه: مساحة القرص وصلت {pct:.0f}% على web-01. راجع اللوجات.")

سيناريو واقعي: لو عندك سيرفر بموقع عليه 50 ألف زائر/يوم، ولوجات بتكبر بسرعة، الفرق بين اكتشاف الامتلاء عند 90% أو عند 100% هو الفرق بين تنظيف هادئ وتوقّف كامل للخدمة. السكربت ده بيديك النافذة دي.

خلّيها تشتغل لوحدها بـ cron

احفظ الكود في /opt/alerts/disk_check.py، وخلّي cron يشغّله كل 5 دقائق:

# افتح المحرّر: crontab -e ثم أضف السطر
*/5 * * * * /usr/bin/python3 /opt/alerts/disk_check.py >> /var/log/disk_check.log 2>&1

كده البوت بقى حارس دائم، بيفحص كل 5 دقائق، وبيزعجك بس وقت اللزوم.

أرقام وحدود لازم تعرفها

• الرسالة الواحدة نصها حتى 4096 حرفًا. لو أطول، قسّمها أو اختصرها.
• Bot API بيسمح بحوالي 30 رسالة/ثانية إجمالًا، وحد أقصى تقريبي رسالة/ثانية لنفس المحادثة. للتنبيهات العادية ده أكثر من كافٍ.
• التسليم غالبًا في أقل من ثانيتين، والخدمة مجانية.

الـ trade-off هنا

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

متى لا تستخدم هذه الطريقة

لو ده نظام إنذار حرج لفريق on-call محتاج تصعيد وتناوب وتأكيد استلام، البوت البسيط مش كفاية؛ استخدم أداة زي Opsgenie أو PagerDuty. وكذلك في بيئة معزولة عن الإنترنت أو محكومة بقيود امتثال تمنع إرسال بياناتك لخدمة خارجية. ولو محتاج تبعت آلاف الرسائل في الثانية، هتصطدم بحدود المعدل.

تأكّد إنه بيشتغل

غيّر العتبة مؤقتًا من 90 لـ 1 وشغّل السكربت يدويًا: python3 /opt/alerts/disk_check.py. المفروض توصلك رسالة فورًا. لو وصلت، رجّع العتبة لـ 90. لو ما وصلتش، اتأكد من التوكن و chat_id، وإن السيرفر بيوصل api.telegram.org.

الخطوة التالية

افتح تيليجرام دلوقتي، اعمل بوت بـ /newbot، واجلب chat_id، وابعت رسالة الاختبار بأمر الـ curl فوق. أول ما توصلك، إنت جاهز تربطها بأي فحص تاني: استهلاك المعالج، أو رجوع خدمة بعد كراش. ابدأ بواحد بس النهاردة.

المصادر

• توثيق Telegram Bot API الرسمي وطُرق sendMessage وgetUpdates: core.telegram.org/bots/api
• إنشاء البوت عبر BotFather: core.telegram.org/bots/features#botfather
• حدود المعدل في Bot API: core.telegram.org/bots/faq
• دالة shutil.disk_usage في بايثون: docs.python.org/3/library/shutil
• مكتبة requests: requests.readthedocs.io
• جدولة المهام عبر cron (crontab): man7.org/linux/man-pages/man5/crontab.5