دليل بناء بوت تفاعلي على تيليجرام خطوة بخطوة

تليجرام من أشهر تطبيقات التراسل الفوري لديها عدد كبير من المستخدمين توفر مزايا كبيرة للمستخدمين والمطورين، أهمها برنامج الرد الآلي بوت Bot الذي يوفر واجهة بسيطة وسهلة للمستخدمين لاستقبال الرسائل منهم وأتمتة المهام برمجيًا.

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

في هذا المقال سننشئ بوت تليجرام باستخدام بايثون Python وإطار العمل فلاسك Flask يعرض صورة رمزية مصغرة avatar من موقع Adorable Avatars، وسننشره على Heroku.

تطوير تطبيق البوت

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

• تثبيت نسخة بايثون python ومعرفة أساسيات البرمجة باستخدام بايثون.
• تثبيت نظام التحكم بالإصدارات Git ومعرفة أساسيات التعامل معه
• معرفة بأساسيات التعامل مع إطار العمل فلاسك Flask
• وجود حساب على تليجرام

إنشاء بوت تليجرام جديد

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

لإنشاء بوت جديد نستخدم الأمر newbot/ ليسألنا بعده عن تحديد اسم البوت الجديد سيظهر للمستخدمين واختيار اسم المستخدم له والذي يجب أن ينتهي بكلمة bot.

سنحصل بعدها على رمز الوصول Access Token الخاص بالبوت الجديد، ومن الضروري الاحتفاظ بهذا الرمز وباسم المستخدم الذي اخترناه لاستخدامهما لاحقًا.

إعداد المشروع في بايثون

نُنشئ بيئة عمل افتراضية جديدة لعزل متطلبات مشروعنا عن البيئة العامة للغة بايثون ونفعّلها ضمن مجلد اسمه botenv (يمكن اختيار أي اسم آخر) سيحتوي على جميع مكتبات بايثون التي سنستخدمها بتنفيذ الأوامر:

python -m venv botenv/
botenv/bin/activate

سنحتاج للمكتبات التالية لبرمجة البوت:

• إطار عمل flask لبناء تطبيقات الويب
• مكتبة بايثون python-telegram-bot توفر واجهة برمجية لتليجرام
• مكتبة بايثون requests الشهيرة للتعامل مع طلبات HTTP

ننزلها باستخدام الأمر pip install ونثبتها ضمن الملف requirements.txt بالاستعانة بالأمر pip freeze ليتمكن خادم البوت من تحضريها بعد نشر البوت، وذلك بتنفيذ الأوامر التالية داخل مجلد المشروع:

pip install flask python-telegram-bot requests
pip freeze > requirements.txt

ستكون هيكلة الملفات فى مجلد مشروعنا كالتالي::

• app.py : يحوي الشيفرة الرئيسية لعمل البوت
• telebot/ : مجلد يحتوي على الملفات الخاصة بالبوت
• credentials.py : نخزن في هذا الملف المتغيرات الحساسة كاسم المستخدم ورمز الوصول
• init.py : ملف خاص في بايثون يحدد أن المجلد الذي يحتوي عليه هو حزمة Package

├── app.py 
├── telebot 
│   ├── credentials.py 
│   |   . 
│   |   you can build your engine here 
│   |   . 
│   └── __init__.py 
└── botenv

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

bot_token = "رمز الوصول الخاص بالبوت الجديد" 
bot_user_name = "اسم المستخدم للبوت الجديد"
URL = "عنوان نطاق خادم البوت"

ضمن ملف التطبيق الرئيس app.py نستورد المكتبات التي سنحتاجها، وننشئ الكائن bot من مكتبة python-telegram-bot للتفاعل مع البوت عبر الواجهة البرمجية، وننشئ الكائن app من مكتبة flask لتعريف التطبيق:

# استيراد المكتبات
from flask import Flask, request 
import telegram from telebot.credentials 
import bot_token, bot_user_name, URL # متغيرات سنستخدمها لاحقًا

global bot 
global TOKEN 
TOKEN = bot_token # رمز الوصول
bot = telegram.Bot(token=TOKEN) # كائن للتفاعل مع البوت
app = Flask(__name__) # كائن تطبيق الويب

##
## سنضيف موجهات التطبيق هنا
##

if __name__ == '__main__':
    app.run(threaded=True)

تعريف موجهات التطبيق

نعرف موجه Route من الشكل {token}/ سيستدعيه تيليجرام لكل رسالة جديدة تُرسل للبوت وفيه سنستخرج محتوى الرسالة ونرد عليها، فإذا كان نصها أمر البدء start/ وهو زر افتراضي يظهر للمستخدمين في أول مرة يتعاملون فيها مع أي بوت سنرسل رسالة ترحيب وشرح للمستخدم عن ما يفعله هذا البوت.

أما إذا كانت رسالة عادية فنستخرج من نصّها الأحرف والأرقام فقط لإنشاء رابط للصورة المقابلة للنص الذي أرسلة المستخدم عبر الواجهة البرمجية للموقع adorable.io ونرسل تلك الصورة للمستخدم عبر البوت.

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

# موجه استقبال الرسائل
@app.route('/{}'.format(TOKEN), methods=['POST'])
def respond():
   # تحويل جسم الطلب الوارد إلى كائن تلغرام
   update = telegram.Update.de_json(request.get_json(force=True), bot)

   chat_id = update.message.chat.id
   msg_id = update.message.message_id

   # استخراج نص الرسالة القادمة
   text = update.message.text.encode('utf-8').decode()

   print("got text message :", text)

   # إرسال رسالة ترحيب عند بدء المستخدم التفاعل مع البوت
   if text == "/start":
       # رسالة الترحيب
       bot_welcome = """
       مرحبًا بك، أرسل لي اسمك وسأولد لك صورة شخصية مناسبة
       """
       # إرسال الرسالة
       bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

   else:
       try:
           # استخراج الأحرف والأرقام من نص الرسالة
           text = re.sub(r"\W", "_", text)
           # إنشاء رابط الصورة بناءًا على الرسالة
           url = "https://api.adorable.io/avatars/285/{}.png".format(text.strip())
           # إرسال الصورة للمستخدم
           bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)
       except Exception:
           # إرسال رسالة في حالة حدوث خطأ من طرفنا
           bot.sendMessage(chat_id=chat_id, text="حدث خطأ، جرب اسمًا آخر لأولد لك صورة مقابله", reply_to_message_id=msg_id)

   return 'ok'

يمكننا الاستعلام عن الرسائل الجديدة الواردة للبوت عبر دالة من الواجهة البرمجية API في فترات زمنية ثابتة، ولكن يتيح تيلجرام طريقة أسهل عبر خطافات الويب Webhooks، فبدلًا من إرسال طلبات للسؤال من طرفنا سيعلمنا تيلجرام بالرسائل الجديدة عبر إرسال طلب من النوع POST لخادمنا يتضمن معلومات عن الرسالة.

يجب إعلام تيليجرام ولمرة واحدة بالرابط المحدد ضمن تطبيقنا لإرسال إشعارات بالرسائل الجديدة إليه، لذا سننشئ موجه جديد سنستدعيه يدويًا لمرة واحدة يستدعي بدوره الدالة setWebhook لإعداد الخطاف كالتالي:

@app.route('/setwebhook', methods=['GET', 'POST'])
def set_webhook():
    # إخبار تيليجرام برابط الخطاف في تطبيقنا
    s = bot.setWebhook('{URL}/{TOKEN}'.format(URL=URL, TOKEN=TOKEN))

    # فحص إتمام العملية بنجاح
    if s:
        return "تم إعداد الخطاف بنجاح"
    else:
        return "فشلت عملية إعداد الخطاف"

أصبح بذلك تطبيق البوت جاهزًا وبقي نشره على الخادم ثم الذهاب لموجه إعداد الخطاف ليبدأ البوت بالعمل، وبذلك يصبح محتوى ملف app.py كاملًا كالتالي:

# استيراد المكتبات
from flask import Flask, request 
import telegram from telebot.credentials 
import bot_token, bot_user_name, URL  

global bot 
global TOKEN 
TOKEN = bot_token # رمز الوصول
bot = telegram.Bot(token=TOKEN) # كائن للتفاعل مع البوت

app = Flask(__name__)

# موجه تلقي الاشعارات
@app.route('/{}'.format(TOKEN), methods=['POST'])
def respond():
   # تحويل جسم الطلب الوارد إلى كائن تلغرام
   update = telegram.Update.de_json(request.get_json(force=True), bot)

   chat_id = update.message.chat.id
   msg_id = update.message.message_id

   # استخراج نص الرسالة القادمة
   text = update.message.text.encode('utf-8').decode()

   print("got text message :", text)

   # إرسال رسالة ترحيب عند بدء المستخدم التفاعل مع البوت
   if text == "/start":
       # رسالة الترحيب
       bot_welcome = """
       مرحبًا بك، أرسل لي اسمك وسأولد لك صورة شخصية مناسبة
       """
       # إرسال الرسالة
       bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

   else:
       try:
           # استخراج الأحرف والأرقام من نص الرسالة
           text = re.sub(r"\W", "_", text)
           # إنشاء رابط الصورة بناءًا على الرسالة
           url = "https://api.adorable.io/avatars/285/{}.png".format(text.strip())
           # إرسال الصورة للمستخدم
           bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)
       except Exception:
           # إرسال رسالة في حالة حدوث خطأ من طرفنا
           bot.sendMessage(chat_id=chat_id, text="حدث خطأ، جرب اسمًا آخر لأولد لك صورة مقابله", reply_to_message_id=msg_id)

   return 'ok'

# موجه إعداد الخطاف
@app.route('/setwebhook', methods=['GET', 'POST'])
def set_webhook():
    # إخبار تيليجرام برابط الخطاف في تطبيقنا
    s = bot.setWebhook('{URL}/{TOKEN}'.format(URL=URL, TOKEN=TOKEN))

    # فحص إتمام العملية بنجاح
    if s:
        return "تم إعداد الخطاف بنجاح"
    else:
        return "فشلت عملية إعداد الخطاف"

if __name__ == '__main__':
   app.run(threaded=True)

تحضير خادم Heroku ونشر البوت

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

نبدأ بإنشاء ملف جديد بالاسم Procfile وهو ملف خاص بمنصة هيروكو نعرّف فيه بطريقة تشغيل التطبيق بإضافة السطر التالي:

web: gunicorn app:app

نذهب لحسابنا على المنصة ومن لوحة التحكم Dashboard وننشئ تطبيق جديد بالضغط على Create new app بعدها سيعاد توجيهنا إلى صفحة النشر Deploy page، وفيها ننتقل لعلامة التبويب Settings وننسخ رابط نطاق التطبيق Domain ونضعه ضمن الملف credentials.py كقيمة للمتغير URL.

نعود لمجلد المشروع وننفذ ضمن الطرفية أمر تسجيل الدخول إلى المنصة كالتالي:

heroku login -i

تحضير مستودع Git

نهيئ مستودع Git في مجلد المشروع ونثبت التغييرات ضمنه ونحدد الفرع الوجهة لدفع المستودع إليه للنشر، وذلك بتنفيذ الأمر التالي مع استبدال اسم المشروع بالاسم الذي حددناه أثناء إنشاء التطبيق على المنصة:

git init
git add . 
git commit -m "first commit"
heroku git:remote -a {اسم-المشروع}

يمكن أيضًا إضافة ملف gitignore. إلى مجلد الجذر للمشروع قبل الدفع كي لا تُرفع الملفات الغير مستخدمة إلى المستودع وضمن الخادم.

نشر المشروع

نحتاج فقط لدفع تغييرات مستودع المشروع في كل مرة نعدل فيها على التطبيق، وذلك بدفع الفرع الحالي بتنفيذ الامر:

git push heroku master

ستظهر رسائل تقدم البناء في الطرفية terminal وفي حال عدم وجود مشاكل سنرى خرج مشابه للتالي عند انتهائها سيكون التطبيق تم رفعه ونشره وأصبح جاهز للاستخدام:

remote: -----> Launching...
remote:        Released v6
remote:        https://project-name.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.

إعداد الخطاف Webhook

جهزنا سابقًا رابط ضمن التطبيق لإعداد الخطاف للبوت مع تيليجرام يجب نزوره لمرة واحدة ضمن المتصفح لإتمام الإعداد عندها ستظهر رسالة النجاح تم إعداد الخطاف بنجاح يصبح بعدها البوت جاهزًا للتحدث معه، وهو عنوان نطاق التطبيق على المنصة مضافًا في نهايته setwebhook/ ويكون مشابهًا للتالي:

https://appname.herokuapp.com/setwebhook

تجربة البوت

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

إضافة ميزات للبوت

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

# إعلام المستخدم أن البوت يكتب رسالة
bot.sendChatAction(chat_id=chat_id, action="typing")

# إرسال الرسالة
bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

#أو أن البوت يرسل لك صورة الآن كي يعلم أن البوت يتفاعل معه بتحديث حالة البوت قبل سطر إرسال الصورة كالتالي
# إعلام المستخدم أن البوت يرسل صورة
bot.sendChatAction(chat_id=chat_id, action="upload_photo")

# إرسال الصورة للمستخدم
bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)

ومثلًا يمكن توليد الردود للبوت عبر الذكاء الاصطناعي، أو أن يستخدم البوت أدوات معينة برمجيا مثلا الاطلاع على حالة الطقس أو الأسعار أو نتائج المباريات ويجيب المستخدم بما يريد، ويمكنك الاطلاع على بوتات أخرى منشورة أو أمثلة عن بوتات تستخدم مزايا مختلفة من تيليجرام مطورة باستخدام بايثون من صفحة python-telegram-bot على GitHub.

الخاتمة

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

ترجمة وبتصرف للمقال Building Your First Telegram Bot: A Step by Step Guide لكاتبه Ali Abdel Aal

اقرأ أيضًا

• بناء بوت Bot تلغرام باستخدام لارافيل وبوتمان BotMan
• تعلم بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask بلغة بايثون
• كيفية التعامل مع الأخطاء في تطبيقات فلاسك Flask
• أساسيات لغة بايثون Python