هل تتذكر أول مرة سمعت فيها عن "بوت تيليجرام"؟
أنا أتذكر. كان صديقي يتحدث بحماس عن بوت يرسل له توقعات الطقس كل صباح. وقتها فكرت: "يا إلهي، هذا معقد. أنا لست مبرمجاً لأفعل هذا."
بعد 48 ساعة، كان أول بوت لي يعمل.
لم أكن خبيراً. لم أفهم كل شيء. لكنني بنيته.
وهذا بالضبط ما سنفعله اليوم. سأريك كيف تبني أول بوت تيليجرام لك، حتى لو كانت هذه أول مرة في حياتك ترى فيها كوداً برمجياً. بحلول نهاية هذا الدليل، سيكون لديك بوت حقيقي، يعمل، يرد على الناس.
الخلاصة في دقيقة (للمستعجلين فقط)
إذا كنت مستعجلاً وتريد الزبدة، فهذا ما ستفعله:
- افتح تيليجرام، ابحث عن BotFather، أرسل له
/newbot، واختر اسماً لبوتك - انسخ التوكن (Token) الذي يعطيك إياه. احفظه عندك ولا تشاركه مع أحد
- افتح محرر نصوص على جهازك (أي شيء، حتى المفكرة)، وانسخ كود بايثون بسيط (سأعطيك إياه جاهزاً بعد قليل)
- ثبّت بايثون ومكتبة واحدة فقط (سطر واحد في terminal)
- شغّل الكود. اذهب للبوت في تيليجرام. أرسل
/start. شاهد الرد.
هذا كل شيء. 5 خطوات. البقية تفاصيل وتعمق.
الآن، لنفهم ما الذي يحدث حقاً وراء الكواليس.
ما هو Telegram Bot API بالضبط؟ (تعريف من قلب الحدث)
ليس تعقيداً... هو مجرد "نادل" بينك وبين تيليجرام
تخيل أنك في مطعم. أنت جائع وتريد الطعام، لكنك لا تستطيع دخول المطبخ. هناك "نادل" وظيفته الوحيدة: أخذ طلبك من الطاولة، إيصاله للطباخ، ثم إعادة الطعام لك.
Telegram Bot API هو هذا النادل بالضبط.
أنت تبني برنامجاً (البوت). هذا البرنامج لا يستطيع التحدث مع تيليجرام مباشرة (المطبخ مغلق). لكنه يستطيع إرسال "طلبات" إلى Telegram Bot API (النادل). الـ API يفهم هذه الطلبات، يوصلها لخوادم تيليجرام العملاقة، ويعود بالرد.
أنت تقول: "أرسل رسالة 'مرحباً' للشخص رقم 1234". الـ API يفعلها.
هذه هي الحقيقة: الـ API ليس شيئاً مخيفاً. إنه مجرد طريقة منظمة للتحدث مع تيليجرام. فترة.
لماذا يستخدم الجميع هذه الواجهة؟ (الفائدة الحقيقية من أول يوم)
لأنك بدونها... لا يمكنك بناء بوت. ببساطة. لكن الفائدة الأعمق هي:
- التجريد: أنت لا تحتاج أن تفهم كيف تعمل خوادم تيليجرام في العمق. الـ API يخفي عنك كل التعقيد. تركز على منطق بوتك فقط.
- القوة: بهذه الواجهة البسيطة، تستطيع بناء كل شيء: من بوت ترحيبي بسيط إلى متجر كامل يعمل بالكامل داخل تيليجرام.
- المجانية المطلقة: Telegram Bot API مجاني. إلى الأبد. مهما كبر بوتك.
هل فهمت هذه النقطة؟ عظيم. لأن هذا هو الأساس الذي ستبني عليه كل شيء.
الأدوات التي تحتاجها قبل أن تبدأ (لن تحتاج أكثر من هذا)
سأكون صريحاً معك: معظم أدلة المبتدئين تخيفك بقائمة طويلة من "المتطلبات". معي، الأمر أبسط.
حساب تيليجرام + بوت أب = بوابتك الوحيدة
أولاً، تحتاج إلى حساب على تيليجرام. أعتقد أن لديك واحداً بالفعل، وإلا ما كنت لتقرأ هذا المقال أصلاً.
ثانياً، وفي داخل تيليجرام نفسه، هناك البوت السحري الوحيد الذي تحتاجه: BotFather. هذا هو أب كل البوتات. هو المسؤول عن "تسجيل" بوتك الجديد رسمياً في شبكة تيليجرام، وإعطائه اسماً، والأهم... التوكن.
التوكن (Token) هو كلمة مرور بوتك. سلسلة طويلة من الأرقام والحروف. من يمتلكها يتحكم في بوتك. سنتحدث عنه كثيراً بعد قليل.
تحذير: أعرف شخصاً أرسل توكنه لصديقه بالخطأ. في اليوم التالي، كان البوت يرسل إعلانات سبام لكل من يستخدمه. لا تكرر غلطته.
Python أم لا؟ (اختيار لغة البرمجة بصدق)
هنا حيث أسمع السؤال الخائف: "ما هي لغة البرمجة التي يجب أن أتعلمها؟"
اسمع. هناك إجابتان: الإجابة الدبلوماسية، وإجابة الأخ الصادق.
الإجابة الدبلوماسية: "أي لغة تدعم HTTP Requests. Python, JavaScript, PHP, Java... كلها تعمل."
إجابة الأخ الصادق: للمبتدئ الذي يريد أول بوت في أسرع وقت وبأقل ألم... Python هي الرفيق المثالي. والسبب؟ مكتبة اسمها python-telegram-bot. هذه المكتبة تتعامل مع كل تعقيدات الـ API نيابة عنك. تنسى تماماً أن هناك API. تركز على "ماذا أفعل عندما يصلني أمر /start؟". فقط.
وهناك منافسة قوية. في مقالتي المفصلة عن أفضل مكتبات Python لإنشاء بوتات تيليجرام (مقارنة عملية للمطورين)، قارنت بينها جميعاً. لكن لرحلتنا اليوم، python-telegram-bot هي البطلة بلا منازع.
ملاحظة: إذا كنت مبرمج JavaScript محترف، فأنت لست بحاجة لهذه الفقرة. لكن للمبتدئ الحقيقي، بايثون هي الأبسط.
التشريح العملي: كيف يعمل البوت من الداخل؟
قبل أن نكتب سطراً واحداً من الكود، دعني أحكِ لك قصة. قصة رسالة.
قصة "الرسالة" من هاتف المستخدم إلى البوت والعكس
- المستخدم (لنسميه خالد) يفتح بوتك على هاتفه.
- يكتب خالد: "
/start". يضغط إرسال. - هذه الرسالة لا تذهب إلى بوتك مباشرة. أبداً. تذهب أولاً إلى خوادم تيليجرام المركزية.
- خوادم تيليجرام تقول: "أوه، هذه الرسالة موجهة للبوت فلان. هل هذا البوت مهتم؟". البوت "مهتم" لأنه ينتظر. هناك طريقتان لانتظار البوت:
Long Polling vs Webhook (شرح بالمشاوي والكباب)
تخيّل في نفس المطعم السابق. أنت نادل.
- الطريقة الكسولة (Long Polling): أنت تقف عند باب المطبخ وتسأل كل دقيقة: "جه الطبق؟". تضيع وقتك وطاقتك في السؤال. بسيط، مثالي للبوتات الصغيرة والتجارب.
- الطريقة الاحترافية (Webhook): أنت تعطي الطباخ جرساً. تقول له: "اضرب الجرس بس لما يجهز الطبق". وتقعد ترتاح لغاية ما تسمع الجرس. أسرع، أقل استهلاكاً للموارد، مثالي للبوتات الكبيرة.
درسنا اليوم سيستخدم الطريقة الأولى (Long Polling) لأنها أسهل في البداية. لا تحتاج خادماً على الإنترنت. تشتغل من جهازك وأنت تتعلم. لكن إذا فكرت يوماً في نشر بوت تيليجرام على VPS، فستنتقل لعالم الـ Webhook.
خطوات بناء أول بوت: من الصفر إلى أول رد آلي (الدليل المصور)
حسناً. كفى تنظيراً. حان وقت العمل. هذه هي اللحظة التي تنتظرها.
سأقسمها لثلاث خطوات. إذا توقفت بعد الأولى، سيكون لديك بوت "قانونياً". وإذا أكملت الثالثة، سيكون لديك بوت يرد عليك.
الخطوة 1: ولادة البوت عند BotFather واستخراج التوكن (Token)
افتح تيليجرام. ابحث في مربع البحث عن:
@BotFather
ستجده. الذي بالعلامة الزرقاء. افتح محادثة معه. اضغط على زر "Start" أو اكتب /start.
سيرسل لك قائمة طويلة بالأوامر. تجاهلها الآن. كل ما يهمنا هو أمر واحد:
/newbot
أرسلها. سيبدأ في طرح الأسئلة:
- Alright, a new bot. How are we going to call it? Please choose a name for your bot.
أدخل اسماً لبوتك. أي اسم. مثلاً "بوتي الأول الرهيب". هذا هو الاسم الظاهر. - Good. Now let's choose a username for your bot. It must end in 'bot'.
هنا تدخل اسم المستخدم. يجب أن يكون فريداً وينتهي بكلمةbot. مثلاًmy_awesome_first_bot.
إذا كان الاسم متاحاً (غالباً لن يكون من أول مرة، جرب أسماء غريبة)، سيرد عليك BotFather برسالة احتفالية وفيها مفتاح كنزك الحقيقي:
Done! Congratulations on your new bot...
Use this token to access the HTTP API:
1234567890:ABCdEFgHiJKlMnOpQRStUVWXyz-abcDEFgHI
هذا هو التوكن (Token). انسخه. احفظه. لا تشاركه مع أي أحد. هذا هو مفتاح بيتك. إذا حصل عليه أحد، يتحكم في بوتك بالكامل.
الخطوة 2: كتابة أول 10 أسطر كود في حياتك
الآن سننتقل لجهاز الكمبيوتر. لا تخف. سأعطيك الكود جاهزاً. كل ما عليك هو نسخه.
نصيحة احترافية: الشرط المسبق الوحيد: يجب أن تكون بايثون مُثبّتة على جهازك. إذا لم تكن، اذهب لموقع python.org وحمّلها. أثناء التثبيت، تأكد من وضع علامة صح على "Add Python to PATH". هذا مهم.
افتح الطرفية (Terminal) أو موجه الأوامر (Command Prompt). اكتب هذا الأمر ثم اضغط Enter:
pip install python-telegram-bot
هذا يثبّت المكتبة السحرية. سطر واحد!
الآن، افتح أي محرر نصوص لديك. حتى برنامج "المفكرة" العادي يعمل. انسخ الكود التالي وألصقه فيه:
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
ضع التوكن الخاص بك بين علامتي الاقتباس
TOKEN = "ضع_التوكن_الخاص_بك_هنا"
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text('أهلاً بك في عالم بوتات تيليجرام! بوتك الأول يعمل الآن.')
def main():
app = Application.builder().token(TOKEN).build()
app.add_handler(CommandHandler("start", start))
app.run_polling()
if name == 'main':
main()
استبدل الجملة "ضع_التوكن_الخاص_بك_هنا" بالتوكن الذي نسخته من BotFather. احفظ الملف باسم my_first_bot.py (أو أي اسم، لكن الامتداد .py مهم جداً).
ماذا يفعل هذا الكود بالضبط؟
- يطلب من المكتبة استيراد الأدوات اللازمة.
- يخبرها ما هو توكن بوتك.
- يقول لها: "إذا وصلك أمر
/start، نادي على الدالةstart". - دالة
startتفعل شيئاً واحداً: ترد على المرسل بـ "أهلاً بك...".
الخطوة 3: تشغيل البوت ورؤية السحر يحدث
عد إلى الطرفية (Terminal). اذهب إلى المجلد الذي حفظت فيه ملفك. مثلاً إذا حفظته على سطح المكتب:
cd Desktop
ثم شغّل الملف:
python my_first_bot.py
إذا ظهرت لك رسالة لا تحتوي على أي شيء مخيف باللون الأحمر... فمبروك! بوتك حي ويعمل على جهازك الآن.
اذهب إلى تيليجرام. افتح بوتك. أرسل له:
/start
شاهد الرد. "أهلاً بك في عالم بوتات تيليجرام! بوتك الأول يعمل الآن."
الخلاصة: تهانينا. أنت الآن صانع بوتات. لا شيء يقف في طريقك الآن.
5 أخطاء تدمر تجربتك الأولى (ارتكبتها كلها)
بعد أول نجاح، تأتي أول مشكلة. هذا طبيعي. في الأسابيع الأولى لي، مررت بكل هذه الأخطاء. سأختصر عليك الطريق.
الخطأ 1: مشاركة التوكن مع صديقك "عن طريق الخطأ"
المشهد: أنت فرحان. بوتك شغال. تريد أن توري صديقك الكود. تلتقط له سكرين شوت. ترسلها.
الكارثة: التوكن ظاهر في الصورة.
ما سيحدث: في خلال ساعات، شخص ما (قد لا يكون صديقك، قد يكون الصورة تسربت) يتحكم في بوتك. يغير سلوكه، يسرق بيانات المستخدمين.
الوقاية: عامل التوكن كرقم بطاقتك البنكية. إذا ظهر في كودك بالخطأ، استخدم BotFather فوراً لإبطاله. اكتب له /token ثم اختر البوت، ثم /revoke. سيولد لك توكن جديد ويقتل القديم.
الخطأ 2: توقف الكود عن العمل فجأة (ولماذا هو خطؤك)
المشكلة: كنت تشغل الكود من Terminal، عملت إغلاق للنافذة. فجأة البوت لا يرد.
السبب: الكود كان يعمل "في الذاكرة المؤقتة". عندما أغلقت Terminal، مات الكود. البوت بدون كود هو مجرد اسم فارغ في تيليجرام.
الحل الدائم: لكي يعمل بوتك 24 ساعة، يجب أن يكون الكود يعمل على خادم (سيرفر) لا يُغلق أبداً. هذا بالضبط ما نشرحه في نشر بوت تيليجرام على VPS: شرح كامل + حل أشهر المشاكل.
الخطأ 3: نسيان الـ Handler المناسب للأوامر
الظاهرة: تكتب /start في البوت، يرد. تكتب أي شيء آخر... صمت مطبق. كأن البوت مات.
السبب: في الكود أعلاه، أنت أضفت Handler واحد فقط. قلت للبوت: "استمع لأمر /start وفقط". أي رسالة أخرى، لا يعرف ماذا يفعل بها.
الإصلاح: أضف Handler آخر للرسائل العادية:
from telegram.ext import MessageHandler, filters
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text(update.message.text)
أضف هذا في دالة main()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
هذا يجعل البوت "ببغاء" يرد بنفس ما تقوله. مثالي للاختبار.
نصيحة احترافية: هناك أخطاء أخرى بالتأكيد. لدي مقال كامل عنها: لماذا لا يعمل بوت تيليجرام؟ 10 أخطاء شائعة وحلولها بالتفصيل. إذا تعطل بوتك يوماً، ذلك المقال سينقذك.
ماذا بعد أول بوت؟ خريطة طريقك من هنا
شعور بناء أول بوت يشبه أول مرة تشعل فيها ناراً. ساحر. لكن لا تتوقف هنا.
من بوت يرد إلى بوت يحادث (رحلة التعلم)
بوتك الحالي أبكم. يفهم /start فقط. الخطوة التالية المنطقية هي جعله يفهم كلاماً أكثر:
- تعلم كيف تستقبل رسائل عادية وتحفظها.
- تعلم كيف تبني أزراراً تفاعلية (Inline Keyboards) بدلاً من جعل المستخدمين يكتبون الأوامر.
- تعلم كيف تخزن بيانات بسيطة عن المستخدمين.
هل تريد بوتاً احترافياً؟ هذا ما عليك فعله
إذا وصلت إلى هنا وأنت متحمس، فأنت في بداية طريق ممتع. ستحتاج إلى:
- مقارنة المكتبات: هل
python-telegram-botمناسبة لبوتك المعقد القادم، أم أنaiogramأفضل؟ مقال أفضل مكتبات Python لإنشاء بوتات تيليجرام يجيبك بالتفصيل. - النشر على سيرفر: لن تترك جهازك الشخصي يعمل 24 ساعة. نشر بوت تيليجرام على VPS هو العنوان التالي.
- الربح الحقيقي: أتعلم؟ هناك أشخاص يحققون دخلاً من بوتاتهم. ليس وهماً. لدي تجربة كاملة شاركتها في كم يمكن أن تربح من بوت تيليجرام؟ تجربة واقعية بالأرقام.
الأسئلة الشائعة (FAQ)
هل بناء بوت تيليجرام صعب لدرجة أني لا أستطيع التعلم؟
لا، وهذه كانت فكرة المقال كله. إذا استطعت نسخ كود ولصقه، وتغيير سطر واحد، فأنت تستطيع بناء بوت بسيط اليوم. التعقيد يأتي لاحقاً، عندما تريد بناء بوتات احترافية. وهذا طبيعي.
كم تكلفة بناء بوت تيليجرام؟
الصفر، الصفر، الصفر. Telegram Bot API مجاني. المكتبات مجانية. الاستضافة على جهازك مجانية. عندما تريد بوتاً شغّالاً 24/7، ستدفع تكلفة VPS التي تبدأ من 5 دولارات شهرياً.
كيف ارفع بوت تيليجرام على استضافة مجانية؟
توجد طرق، لكنها غير مستقرة للمشاريع الحقيقية. استخدمها للتعلم فقط. الحل الاحترافي هو VPS. لدي دليل كامل عن هذا.
هل يمكن بناء بوت تيليجرام بدون كود نهائياً؟
نعم، توجد منصات مثل Manybot و Chatfuel. لكنك تضحي بالمرونة. بوتك بدون كود سيبقى محدوداً ولن تستطيع تخصيصه بالكامل. جربها ليوم واحد لترى، لكن الكود هو الحل الحقيقي.
كيف أربط بوت تيليجرام بقناتي؟
ببساطة، أضف البوت كمشرف (Admin) في قناتك. ثم، من داخل الكود، يمكنك استخدام دالة مثل bot.send_message(chat_id='@ChannelUsername', text='...') ليرسل رسائل للقناة نيابة عنك. هذه من أول المهارات المتقدمة التي ستتعلمها.
قائمة المراجعة قبل نشر بوتك الأول (Checklist)
- هل استخرجت التوكن من BotFather وحفظته في مكان آمن؟
- هل التوكن سري، ولم يظهر في أي صورة أو كود شاركته؟
- هل ثبت بايثون ومكتبة
python-telegram-bot؟ - هل استبدلت النص
"ضع_التوكن_الخاص_بك_هنا"بالتوكن الحقيقي؟ - هل جربت أمر
/startمن حساب تيليجرام آخر غير حسابك؟ - هل أضفت Handler للرسائل النصية العادية على الأقل ليرد بصدى الكلام (echo)؟
- هل تعرف أين ستذهب لتحل المشكلة إذا توقف البوت عن العمل بعد إغلاق الكمبيوتر؟
إذن، هذا هو عالم Telegram Bot API كما شرحته لصديق.
ليس مخيفاً، صحيح؟ هو مجرد نادل. بسيط، يؤدي وظيفته. ما يجعله معقداً هو ما تريد أنت بناءه فوقه.
تذكر: كل خبير بوتات بدأ مثلك تماماً. جالساً في مكان ما، ينسخ كوداً من مقال، ويندهش عندما يرى الرد الأول.
ابدأ اليوم. ابنِ شيئاً سخيفاً. بوت يقول نكتاً، بوت يرسل لك آية قرآنية عشوائية، بوت يرد على "أهلاً" بـ "أهلاً فيك".
وابنِ عليه.
إذا واجهتك مشكلة، لا تجلس وحدك. اترك تعليقاً هنا، أو اذهب لمجتمع المطورين. والأرجح أن خطأك هو أحد الأخطاء التي ناقشتها في أخطاء استخدام Python في بوتات تيليجرام (وكيف تتجنبها).
هل بدأت ببناء بوتك الأول بعد؟ ما هو؟ شاركني في التعليقات.
