دليلك الشامل: بناء أول بوت تيليجرام بايثون من الصفر

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

إن سهولة قراءة بايثون والمجتمع النشط الذي يدعم مكتبة python-telegram-bot يجعلانها نقطة انطلاق رائعة لكل من المبتدئين والمطورين ذوي الخبرة. بنهاية هذا الدليل، سيكون لديك بوت تيليجرام يعمل بكامل طاقته وجاهز للتفاعل مع المستخدمين.

أبرز النقاط التي ستتعلمها

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

1. إعداد بوت تيليجرام الخاص بك وبيئة التطوير

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

1.1 إنشاء البوت الخاص بك باستخدام BotFather

الخطوة الأولى لأي بوت تيليجرام هي تسجيله مع BotFather، بوت تيليجرام الرسمي لإدارة البوتات الأخرى.

1. افتح تيليجرام وابحث عن @BotFather: في تطبيق تيليجرام الخاص بك، ابحث عن “@BotFather” وابدأ محادثة. تأكد من أنه البوت الرسمي الذي يحمل علامة التحقق الزرقاء.
2. ابدأ عملية إنشاء البوت: اكتب /newbot وأرسل الرسالة.
3. اختر اسمًا: سيطلب منك BotFather اسمًا لبوتك. هذا هو العنوان الذي يراه المستخدمون (على سبيل المثال، “بوت الرائع”).
4. اختر اسم مستخدم: بعد ذلك، اختر اسم مستخدم فريدًا لبوتك. يجب أن ينتهي بـ “bot” (على سبيل المثال، my_awesome_bot). إذا كان اسم المستخدم مأخوذًا، سيطلب منك BotFather تجربة اسم آخر.
5. احصل على رمز API الخاص بك: بمجرد النجاح، سيوفر لك BotFather رمز HTTP API. هذا الرمز بالغ الأهمية، حيث يعمل ككلمة مرور لبوتك. احتفظ به آمنًا ولا تشاركه علنًا أبدًا. سيبدو شيئًا مثل 123456:ABC-DEF1234ghIkl-zyx57W23L1qR_456.

1.2 تثبيت بايثون و pip

إذا لم يكن لديك بايثون مثبتًا بالفعل، قم بتنزيل أحدث إصدار مستقر من موقع بايثون الرسمي (https://www.python.org/downloads/). أثناء التثبيت، تأكد من تحديد المربع الذي يقول “Add Python to PATH” لتسهيل الوصول عبر سطر الأوامر.

pip هو مثبت حزم بايثون، وعادة ما يأتي مثبتًا مسبقًا مع بايثون. يمكنك التحقق من تثبيت بايثون و pip عن طريق فتح الطرفية أو موجه الأوامر وكتابة:

python --version
pip --version

1.3 تثبيت مكتبة python-telegram-bot

مكتبة python-telegram-bot هي غلاف شائع وقوي لواجهة برمجة تطبيقات بوت تيليجرام. إنها تبسط التفاعلات مع الـ API، مما يجعل تطوير البوت الخاص بك أسهل بكثير.

قم بتثبيتها باستخدام pip:

pip install python-telegram-bot

لقد قمت الآن بإعداد البوت الخاص بك وبيئة التطوير بنجاح. دعنا ننتقل إلى كتابة بعض الأكواد!

2. أول كود بوت تيليجرام بايثون: بوت الصدى

سنبدأ بكلاسيكية: بوت الصدى. هذا البوت سيكرر ببساطة أي رسالة يتلقاها. يعلمك هذا المثال البسيط المفاهيم الأساسية للتعامل مع الرسائل.

2.1 استيراد الوحدات الضرورية

أنشئ ملف بايثون جديد (على سبيل المثال، my_telegram_bot.py) وابدأ باستيراد المكونات المطلوبة من مكتبة telegram.

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters
import logging
import os

• Update: يمثل تحديثًا واردًا من تيليجرام (على سبيل المثال، رسالة جديدة، أمر).
• Application: الفئة الرئيسية التي تدير دورة حياة البوت الخاص بك.
• CommandHandler: يستخدم لتسجيل المعالجات لأوامر محددة (على سبيل المثال، /start, /help).
• MessageHandler: يستخدم لتسجيل المعالجات لأنواع مختلفة من الرسائل (نص، صور، إلخ).
• filters: يوفر فلاتر مريحة لتحديد الرسائل التي يجب أن يستجيب لها MessageHandler.
• logging: ممارسة جيدة لتصحيح الأخطاء وفهم سلوك البوت الخاص بك.
• os: لتحميل رمز API الخاص بك بأمان من متغيرات البيئة.

2.2 إعداد التسجيل (Logging)

التسجيل ضروري لاستكشاف الأخطاء وإصلاحها. أضف الأسطر التالية إلى السكريبت الخاص بك:

# Enable logging
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
)
logger = logging.getLogger(__name__)

2.3 تعريف المعالجات (Handlers) الخاصة بنا

المعالجات هي دوال تعالج التحديثات الواردة.

معالج أمر start:

سيتم استدعاء هذه الدالة عندما يرسل المستخدم الأمر /start.

async def start(update: Update, context):
    """Sends a welcome message when the command /start is issued."""
    user = update.effective_user
    await update.message.reply_html(
        f"مرحباً {user.mention_html()}! أنا بوت صدى. أرسل لي أي شيء وسأكرره!",
        # reply_markup=ForceReply(selective=True), # اختياري: فرض الرد على هذه الرسالة
    )

معالج رسالة echo:

هذه الدالة ستكرر أي رسالة نصية تتلقاها.

async def echo(update: Update, context):
    """Echoes the user message."""
    await update.message.reply_text(update.message.text)

معالج help_command:

أمر مساعدة بسيط.

async def help_command(update: Update, context):
    """Sends a help message."""
    await update.message.reply_text("أرسل لي أي رسالة، وسأكررها لك!")

2.4 دالة main: تجميع كل شيء معًا

دالة main هي المكان الذي نقوم فيه بتهيئة البوت الخاص بنا، وتسجيل المعالجات، وبدء الاستعلام عن التحديثات.

def main() -> None:
    """Start the bot."""
    # Get the API token from environment variables (BEST PRACTICE!)
    # Alternatively, you can hardcode it here for quick testing: TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
    TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not TOKEN:
        raise ValueError("TELEGRAM_BOT_TOKEN environment variable not set.")

    # Create the Application and pass it your bot's token.
    application = Application.builder().token(TOKEN).build()

    # Register handlers
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # Run the bot until the user presses Ctrl-C
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

2.5 تشغيل البوت الخاص بك محليًا

1. عيّن رمز API الخاص بك كمتغير بيئة:

   • Linux/macOS: export TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
   • Windows (موجه الأوامر): set TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE"
   • Windows (PowerShell): $env:TELEGRAM_BOT_TOKEN="YOUR_API_TOKEN_HERE" بدلاً من ذلك، للاختبار المحلي السريع، يمكنك استبدال os.environ.get("TELEGRAM_BOT_TOKEN") بسلسلة الرمز الفعلية الخاصة بك مباشرة في الكود (على سبيل المثال، TOKEN = "123456:ABCDEF...")، ولكن لا يوصى بذلك للإنتاج.

2. شغل سكريبت بايثون الخاص بك: انتقل إلى الدليل الذي حفظت فيه my_telegram_bot.py في الطرفية وشغل:

   python my_telegram_bot.py

3. تفاعل مع البوت الخاص بك: افتح تيليجرام، وابحث عن اسم مستخدم البوت الخاص بك (على سبيل المثال، @my_awesome_bot)، وابدأ محادثة. حاول إرسال /start، /help، أو أي رسالة نصية. يجب أن يستجيب البوت الخاص بك!

تهانينا! لقد قمت للتو بإنشاء وتشغيل أول تطبيق بوت تيليجرام بايثون خاص بك.

3. إضافة ميزات أكثر تقدمًا

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

3.1 التعامل مع أنواع الرسائل المختلفة

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

مثال: الرد على الصور

async def handle_photo(update: Update, context):
    """Responds to a photo with a confirmation message."""
    # You can access photo details via update.message.photo
    # The list contains different sizes of the same photo; the last one is usually the largest.
    photo_file_id = update.message.photo[-1].file_id
    await update.message.reply_text("صورة جميلة! لقد استلمتها.")

# Add this handler in your main function
# application.add_handler(MessageHandler(filters.PHOTO, handle_photo))

3.2 استخدام لوحات المفاتيح المضمنة (Inline Keyboards) ولوحات مفاتيح الرد (Reply Keyboards)

توفر لوحات المفاتيح خيارات تفاعل منظمة للمستخدمين.

• لوحات مفاتيح الرد (Reply Keyboards): تظهر فوق حقل إدخال الرسالة، لتحل محل لوحة المفاتيح القياسية بشكل فعال. رائعة للخيارات المحددة مسبقًا.
• لوحات المفاتيح المضمنة (Inline Keyboards): مرفقة مباشرة برسالة، مع أزرار يمكنها تشغيل استدعاءات (callbacks) أو فتح عناوين URL. مثالية للقوائم التفاعلية.

مثال: لوحة مفاتيح مضمنة (Inline Keyboard)

دعنا نعدل أمر /start الخاص بنا لتقديم أزرار.

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, MessageHandler, CallbackQueryHandler, filters
# ... (other imports and logging) ...

async def start(update: Update, context):
    """Sends a welcome message with an inline keyboard."""
    user = update.effective_user
    keyboard = [
        [InlineKeyboardButton("زر TeleClaw", url="https://teleclaw.bot")],
        [InlineKeyboardButton("عن البوت", callback_data="about")],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_html(
        f"مرحباً {user.mention_html()}! أهلاً بك في بوتي. ماذا تود أن تفعل؟",
        reply_markup=reply_markup,
    )

async def button_callback(update: Update, context):
    """Handles callback queries from inline keyboard buttons."""
    query = update.callback_query
    await query.answer() # Always answer callback queries

    if query.data == "about":
        await query.edit_message_text(text="هذا بوت تجريبي بسيط تم إنشاؤه باستخدام بايثون ومكتبة `python-telegram-bot`.")
    # Add more conditions for other callback_data values

ستحتاج إلى تحديث دالة main الخاصة بك لتضمين CallbackQueryHandler:

    # ... داخل main() ...
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CallbackQueryHandler(button_callback)) # أضف هذا السطر
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    # ...

يوضح هذا كيفية الربط بموقع خارجي مثل TeleClaw وتنفيذ إجراء داخل البوت. يمكنك استكشاف المزيد حول خيارات لوحة المفاتيح المختلفة في وثائق python-telegram-bot (https://docs.python-telegram-bot.org/en/stable/telegram.keyboardbutton.html).

3.3 التكامل مع واجهات برمجة التطبيقات الخارجية (APIs)

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

مثال: استدعاء API بسيط (باستخدام مكتبة requests)

أولاً، قم بتثبيت requests: pip install requests.

import requests

async def get_fact(update: Update, context):
    """Fetches a random fact from an external API."""
    try:
        response = requests.get("https://uselessfacts.jsph.pl/api/v2/facts/random")
        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
        fact_data = response.json()
        await update.message.reply_text(f"هل تعلم؟ {fact_data['text']}")
    except requests.exceptions.RequestException as e:
        logger.error(f"Error fetching fact: {e}")
        await update.message.reply_text("عذرًا، لم أتمكن من جلب حقيقة الآن. يرجى المحاولة مرة أخرى لاحقًا.")

# Add this command handler:
# application.add_handler(CommandHandler("fact", get_fact))

يوضح هذا كيف يمكن للبوت التفاعل مع مصادر البيانات الخارجية، تمامًا كما يتكامل @claw مع خدمات متنوعة لتقديم ميزات متطورة. للتفاعلات المتقدمة مع الذكاء الاصطناعي، فكر في استخدام منصات مثل TeleClaw، التي تجرد تعقيدات التكامل مع نماذج مثل GPT-4 أو Gemini. يمكنك قراءة المزيد حول دمج أدوات الذكاء الاصطناعي في مقالنا حول كيفية بناء بوت محادثة تيليجرام.

4. البيانات المستمرة وإدارة الحالة

بالنسبة للبوتات الأكثر تعقيدًا، ستحتاج إلى طريقة لتخزين البيانات بين التفاعلات. على سبيل المثال، إذا كان البوت الخاص بك يحتاج إلى تذكر تفضيلات المستخدم أو المحادثات الجارية.

4.1 استخدام context.user_data و context.chat_data

توفر مكتبة python-telegram-bot قواميس context.user_data و context.chat_data (المتاحة في دوال المعالج الخاصة بك) التي يمكنها تخزين بيانات مؤقتة مرتبطة بمستخدم أو محادثة. تستمر هذه البيانات طوال مدة تشغيل البوت.

async def set_favorite_color(update: Update, context):
    """Allows users to set their favorite color."""
    if context.args:
        color = " ".join(context.args).strip()
        context.user_data["favorite_color"] = color
        await update.message.reply_text(f"تمام، لقد سجلت لونك المفضل وهو {color}.")
    else:
        await update.message.reply_text("من فضلك أخبرني عن لونك المفضل، على سبيل المثال، /setcolor أزرق")

async def get_favorite_color(update: Update, context):
    """Tells the user their favorite color."""
    color = context.user_data.get("favorite_color")
    if color:
        await update.message.reply_text(f"لونك المفضل هو {color}.")
    else:
        await update.message.reply_text("لا أعرف لونك المفضل بعد. استخدم /setcolor.")

# Add these handlers:
# application.add_handler(CommandHandler("setcolor", set_favorite_color))
# application.add_handler(CommandHandler("getcolor", get_favorite_color))

4.2 استمرارية البيانات عبر إعادة التشغيل

لكي تستمر البيانات حتى عند إعادة تشغيل سكريبت البوت الخاص بك، تحتاج إلى حل أكثر قوة، مثل:

• الملفات (CSV, JSON): بسيطة لكميات صغيرة من البيانات.
• قواعد البيانات (SQLite, PostgreSQL, MongoDB): موصى بها لتخزين البيانات الأكبر والأكثر تعقيدًا. SQLite خيار جيد للتطوير المحلي لأنه يعتمد على الملفات ولا يتطلب خادمًا منفصلاً.
• حلول التخزين من طرف ثالث: قواعد بيانات سحابية مثل Firestore أو DynamoDB.

توفر مكتبة python-telegram-bot أيضًا فئات BasePersistence التي يمكن استخدامها مع PicklePersistence أو DictPersistence لحفظ user_data و chat_data و bot_data في ملف. ارجع إلى الأمثلة الرسمية لـ python-telegram-bot لمعرفة كيفية استخدام الاستمرارية (https://docs.python-telegram-bot.org/en/stable/telegram.ext.basepersistence.html).

5. اعتبارات النشر

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

5.1 الاستقصاء (Polling) مقابل الـ Webhooks

هناك طريقتان أساسيتان يتلقى بهما بوت تيليجرام التحديثات:

• الاستقصاء الطويل (Long Polling): يطلب البوت الخاص بك بشكل متكرر من خوادم تيليجرام تحديثات جديدة. هذا ما استخدمناه مع application.run_polling(). سهل الإعداد ولكنه قد يستهلك الكثير من الموارد للبوتات النشطة جدًا.
• الـ Webhooks: تخبر تيليجرام بعنوان URL لخادمك. عندما يحدث تحديث، يرسل تيليجرام طلب HTTP POST إلى هذا العنوان. أكثر كفاءة للإنتاج، ولكنه يتطلب خادمًا متاحًا للعامة والتعامل مع HTTPS.

بالنسبة للبوتات البسيطة والتطوير الأولي، الاستقصاء الطويل كافٍ. للإنتاج، يفضل استخدام الـ webhooks بشكل عام. تدعم مكتبة python-telegram-bot كليهما.

5.2 منصات النشر

توجد عدة منصات مناسبة لنشر بوتات بايثون:

• Heroku: رائع للمشاريع الصغيرة والمتوسطة، مع طبقة مجانية. سهل النشر باستخدام git.
• Render: مشابه لـ Heroku ولكن غالبًا ما يقدم طبقات مجانية أكثر سخاء وميزات حديثة.
• AWS (EC2, Lambda), Google Cloud (Compute Engine, Cloud Functions), Azure (App Service, Functions): توفر حلولًا قوية وقابلة للتطوير ولكنها تتطلب منحنى تعلم أكثر حدة.
• الخوادم الافتراضية الخاصة (VPS): خدمات مثل DigitalOcean, Linode, Vultr تمنحك مزيدًا من التحكم، ولكنك مسؤول عن إدارة الخادم.

عند النشر، تذكر أن:

• تحافظ على أمان رمز API الخاص بك: استخدم متغيرات البيئة.
• تثبت التبعيات: أنشئ ملف requirements.txt (pip freeze > requirements.txt) وتأكد من أن مضيفك يقوم بتثبيتها.
• تكوّن مديري العمليات: أدوات مثل systemd أو pm2 يمكنها إبقاء البوت الخاص بك يعمل حتى لو تعطل.

للتطبيقات التجارية أو البوتات التي تعمل بالذكاء الاصطناعي والقابلة للتطوير بدرجة عالية، توفر منصات مثل TeleClaw بيئة قوية ومُدارة. إنها تتعامل مع البنية التحتية والأمان والتوسع، مما يتيح لك التركيز على منطق البوت الخاص بك وتجربة المستخدم. اطلع على دليلنا المفصل حول بوت تيليجرام للأعمال لترى ما تقدمه TeleClaw.

الخلاصة

لقد تعلمت الآن المبادئ الأساسية لبناء تطبيق بوت تيليجرام بايثون. من الإعداد الأولي باستخدام BotFather وتكوين البيئة إلى كتابة المعالجات للأوامر والرسائل، والتعامل مع أنواع البيانات المختلفة، والنظر في استراتيجيات النشر، لديك الآن أساس متين. تجعل مكتبة python-telegram-bot التفاعل مع واجهة برمجة تطبيقات تيليجرام أمرًا مباشرًا بشكل مدهش، مما يفتح عالمًا من الإمكانيات للأتمتة والتفاعل.

كلما أصبحت أكثر راحة، يمكنك استكشاف مواضيع متقدمة مثل:

• إدارة المحادثات باستخدام ConversationHandler.
• معالجة الأخطاء والتسجيل القوي.
• التكامل مع قواعد البيانات لتخزين البيانات المعقدة.
• استخدام filters أكثر تقدمًا.
• تطبيق الوضع المضمن لقدرات البحث العالمية.

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

هل أنت مستعد لبناء، أو تحسين، أو إدارة بوتات تيليجرام الخاصة بك بأتمتة ذكية؟

استكشف TeleClaw اليوم وعزز بوت تيليجرام الخاص بك! أو جرب بوتنا مباشرة على تيليجرام: @claw