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

تعلم بناء بوت تيليجرام

بوت تيليجرام برنامج يعمل على خادمك أنت ويرسل طلبات إلى api.telegram.org بتوكن؛ وتيليجرام نفسه لا يشغّل أي كود لك. وإنشاء البوت بـBotFather يستغرق دقائق، والعمل الحقيقي يبدأ حين تقرر كيف تستقبل الرسائل وماذا ترى داخل مجموعة.

  • الدرس 5 من 8
  • مبتدئ
  • مجاني، دون تسجيل

من الصفر إلى بوت يرد

الخطوات الأربع الأولى تنتهي في دقائق. والخامسة هي التي تعرّف المشروع.

  1. BotFather

    أمر newbot واسم ظاهر واسم مستخدم ينتهي بـbot.

    1

  2. التوكن

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

    2

  3. اختبار بـgetMe

    طلب واحد قبل كتابة أي كود. والجواب دائماً JSON حتى حين يكون خطأ.

    3

  4. الأوامر الأولى

    start وأمر أو أمران آخران، مسجلة في BotFather كي تظهر في قائمة الاقتراحات.

    4

  5. الاستضافة والبقاء عاملاً

    على البرنامج أن يعود بعد إعادة التشغيل. والتحديثات لا تُحفظ أكثر من يوم.

    5

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

آخر مراجعة: تُراجع الحقائق وأسماء الأدوات في هذا الدرس مقابل مصادرها في هذا التاريخ.

ما هو بوت تيليجرام بالضبط وكيف يعمل؟

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

وطريقة الحديث نمط بسيط، ووثائق Bot API تكتبه هكذا بالضبط: كل الاستعلامات يجب أن تُقدَّم عبر HTTPS وبهذا الشكل: https://api.telegram.org/bot<token>/METHOD_NAME. فكل ميثود عنوان. والرد دائماً كائن JSON يحمل حقل ok.

والتوكن هو ما تسميه الوثائق توكن المصادقة، وتقول إن كل بوت يُمنح واحداً خاصاً به عند إنشائه؛ وشكله شيء مثل 123456:ABC-DEF.... ولهذه الجملة معنيان والثاني أهم: التوكن ليس مفتاحاً بجانبه كلمة سر، بل التوكن هو الهوية نفسها. فمن يملك تلك السلسلة هو بوتك.

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

تعلم بناء بوت تيليجرام: من BotFather إلى أول رسالة

من BotFather إلى أول رسالة، خطوة بخطوة

تيليجرام نفسه لا ينشئ البوت؛ بل بوت اسمه @BotFather. تقصده في تيليجرام وترسل /newbot، وتعطيه اسماً ظاهراً واسم مستخدم ينتهي بـbot، فيسلّمك التوكن. ويمكنك هناك أيضاً تسجيل قائمة الأوامر، وهو ما تغفله معظم الدروس وهو بالضبط ما يرفع قائمة الاقتراحات حين يكتب المستخدم شرطة مائلة. وبحسب الوثائق تبدأ الأوامر دائماً بعلامة / ولا تتجاوز 32 محرفاً.

وقبل كتابة أي كود جرّب التوكن. طلب واحد يكفي:

curl -s "https://api.telegram.org/bot<token>/getMe"

فإن كان التوكن صحيحاً حصلت على بيانات البوت بصيغة JSON. وإن كان خاطئاً فالعائد ليس صفحة خطأ HTTP بل الظرف نفسه بصيغة JSON. جربناه اليوم من خادمنا بتوكن مختلق وكان الجواب هذا بالضبط:

{"ok":false,"error_code":401,"description":"Unauthorized"}

ونعرضه عمداً، لأن شكل العمل كله في هذا السطر: ok يقول أنجح أم لا، وإن لم ينجح فـdescription يقول لماذا. وعلى برنامجك أن ينظر إلى ok أولاً دائماً لا إلى رمز حالة HTTP وحده.

وبعد ذلك أول ما ينبغي أن يعرفه البوت هو الرد على /start، لأنها الزر الذي يفتحه به المستخدم. اكتب جملة واحدة تقول ماذا يفعل البوت وماذا يضغط المستخدم بعدها. فالبوت الذي يرد على /start رداً غامضاً يُغلق هناك.

أأستقبل الرسائل بـgetUpdates أم بويبهوك؟

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

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

وفي الوضع الثاني تعطي عنواناً فيرسل تيليجرام إليه طلب POST عبر HTTPS كلما وُجد شيء. وهو أكفأ وهو الجواب الصحيح لبوت كثيف الحركة. واعرف أمرين من الوثائق نفسها: إن رد عنوانك برمز غير 2XX كرر تيليجرام الطلب ثم تخلى بعد عدد معقول من المحاولات. والأهم أن التحديثات الواردة تُخزَّن على خادم تيليجرام حتى يستقبلها البوت، لكنها لا تُحفظ أكثر من 24 ساعة.

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

طريقتان لاستقبال الرسائل، وهما لا تجتمعان

أللبوت عنوان HTTPS عام؟

إن لم يكن، أو كنت في البداية

getUpdates

  • يعمل على حاسوب محمول بلا نطاق ولا شهادة
  • عليك إعادة حساب offset بعد كل رد
  • يكفي للتعلم وللنسخة الأولى
إن كان لديه والحركة كثيفة

ويبهوك

  • يرسل تيليجرام طلب POST عبر HTTPS لكل تحديث
  • رد بغير 2XX يجعل تيليجرام يكرر الطلب
  • أكفأ ويحتاج خادماً متاحاً دائماً

تقول الوثائق إن الاثنين متنافيان. فإن ضُبط ويبهوك فلا يرد getUpdates إطلاقاً.

ماذا يرى البوت داخل مجموعة؟

هذا القسم هو سؤال الخصوصية وسبب أن بوتك «لا يعمل» في مجموعة في آن. فلدى تيليجرام وضع اسمه Privacy Mode مفعّل افتراضياً لكل بوت يُضاف إلى مجموعة، وفيه لا يرى البوت إلا هذه: الأوامر الموجهة إليه صراحةً مثل /command@this_bot؛ والأوامر العامة مثل /start إن كان آخر بوت أرسل رسالة إلى المجموعة؛ والرسائل الإنلاين المرسلة عبره؛ والردود على رسائل موجهة إلى هذا البوت.

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

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

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

ماذا يرى البوت في مجموعة مع الوضع الافتراضي

  • أمر موجه إليه صراحةً

    صيغة command@this_bot، أي أن المستخدم حدد أي بوت يخاطب.

  • أمر عام بشرط واحد

    مثل start، لكن فقط إن كان هذا البوت آخر بوت أرسل رسالة إلى المجموعة.

  • رسالة إنلاين مرسلة عبره

    شيء أنشأه المستخدم بكتابة اسم البوت داخل تلك المحادثة.

  • ردود على رسائل موجهة إليه

    ولهذا يقترح تيليجرام force reply بدل إطفاء وضع الخصوصية.

  • باقي محادثة المجموعة، لا

    وأعضاء المجموعة يستطيعون رؤية إعداد الخصوصية لأي بوت في قائمة الأعضاء.

استثناء واحد: البوتات المضافة كمشرفين تستقبل كل الرسائل دائماً.

الحدود والأخطاء التي يقع فيها الجميع أول مرة

ثمة ثلاث عائلات من الحدود وكلها مكتوبة في الأسئلة الشائعة الرسمية. الأولى معدل الرسائل: في محادثة واحدة تجنب إرسال أكثر من رسالة في الثانية؛ ويقول تيليجرام إنه قد يسمح بدفقات قصيرة فوق ذلك لكنك ستبدأ في النهاية بتلقي أخطاء 429. وفي مجموعة لا يستطيع البوت إرسال أكثر من 20 رسالة في الدقيقة. وللإشعارات الجماعية لا يبث البوت أكثر من نحو 30 رسالة في الثانية.

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

والثالثة الملفات. يرسل البوت ملفات حتى 50 ميجابايت، وميثود getFile لا يعمل إلا مع ملفات حتى 20 ميجابايت. والرقمان ليسا واحداً، وهنا بالضبط يعمل بوت يستقبل فيديو في الاختبار وينكسر بين يدي مستخدم حقيقي.

وثلاثة أخطاء تتكرر. الأول وضع التوكن داخل كود يُنشر على غيت هب؛ ولأن التوكن هو هوية البوت نفسها فكل من يراه يستطيع إرسال الرسائل بدلاً منك. ومكان التوكن متغير بيئة لا ملف كود. والثاني إرسال الرسائل في حلقة بلا تباعد، وهو ما يمضي مباشرة إلى الخطأ 429. والثالث افتراض أن البوت يعمل دائماً: فبرنامجك سيتعطل يوماً، وإن بقي متوقفاً أكثر من 24 ساعة فرسائل تلك المدة لا تعود.

قبل أن تضع البوت بين يدي مستخدم

ورقة مراجعة قبل التشغيلقبل النشر

افحص هذه

  • التوكن في متغير بيئة وليس في أي ملف يُنشر
  • الكود يقرأ حقل ok في الرد قبل كل شيء
  • الإرسال الجماعي متباعد ويعالج الخطأ 429
  • رسالة start تقول ماذا يفعل البوت وماذا يقرأ
  • البرنامج يعود بنفسه بعد إعادة تشغيل الخادم

لا تفعل هذه

  • إطفاء وضع الخصوصية لأنه أسهل
  • التعويل على البث المدفوع لبوت جديد
  • افتراض أن getFile يعمل مع ملف كبير أيضاً
  • ضبط ويبهوك ثم التعجب لماذا لا يرد getUpdates

هذه الورقة لا تجعل البوت بلا عيب. بل تمنع الأخطاء الثلاثة التي يكلّف التراجع عنها أكثر من منعها.

المسار السريع مع الذكاء الاصطناعي

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

  1. اكتب ما ينبغي أن يفعله البوت بلغة بسيطة كأنك تشرح لمتدرب. أي أوامر وأي ردود وماذا يخزّن وأين.
  2. شغّل الوصفة أدناه. ولا تضع التوكن الحقيقي في الأمر؛ فالوصفة تطلب من النموذج صراحةً أن يقرأ التوكن من متغير بيئة.
  3. اقرأ الكود قبل تشغيله ومرّر عليه البنود الثلاثة نفسها من ورقة المراجعة أعلاه: أين التوكن، وكيف يُعالَج الخطأ 429، وماذا يُقرأ داخل مجموعة.
  4. نفّذ التشغيل الأول ببوت ثانٍ لا بالبوت الحقيقي. والوثائق تقترح ذلك بعينه: أنشئ بوتاً جديداً واستعمل توكنه في نسخة الاختبار واترك البوت الحقيقي دون مساس.

وصفة جاهزة للنسخ

اكتب بوت تيليجرام يقوم بهذا:
{وصف بسيط لما ينبغي أن يفعله البوت}

قواعد صارمة:
1) اقرأ التوكن من متغير بيئة ولا تكتب أي توكن في الكود ولو كمثال.
2) بعد كل طلب، افحص حقل ok في الرد أولاً وسجّل قيمة description إن كان false. ولا تعتمد على رمز حالة HTTP وحده.
3) للإرسال إلى عدة أشخاص، ضع تأخيراً بين الرسائل وعالج الخطأ 429؛ ولا ترسل أكثر من رسالة في الثانية في محادثة واحدة.
4) استعمل getUpdates لا ويبهوك، وأعد حساب offset بعد كل رد.
5) افترض أن وضع الخصوصية مفعّل في المجموعات، فعالج الأوامر الموجهة صراحةً إلى هذا البوت فقط.
6) حيثما لم تكن واثقاً أن الواجهة فيها ميثود ما، اترك تعليقاً نصه «يجب التحقق في الوثائق» بدل التخمين وتابع.

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

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

الذكاء الاصطناعي في هذا العمل

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

أدوات تساعد فعلا

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

اين ينقلب ضدك

الخطر الأول هنا أوضح منه في أي درس آخر في هذا المسار واسمه التوكن. فإن ألصقت توكن البوت في أمر فقد أرسلته إلى خدمة خارجية، ولأن التوكن هو هوية البوت لا مفتاحاً بجانب كلمة سر فإن كشفه يعني أن أحدهم يستطيع مراسلة كل مستخدميك باسمك. وهل تحتفظ الخدمة ببياناتك للتدريب أم لا فيتوقف على الخطة وإعدادات تلك الخدمة وهو مكتوب في صفحة استعمال البيانات لديها؛ لكن أياً كان الجواب فإرسال التوكن غير لازم. والوصفة أعلاه تطلب من النموذج عمداً أن يقرأ التوكن من متغير بيئة.
والخطر الثاني اختراع الميثودات. فلواجهة تيليجرام أسماء حسنة الصياغة والنموذج يولّد بسهولة اسماً يشبهها ولا وجود له. والعرض يظهر متأخراً، لأن الكود يُترجم ولا تحصل على خطأ «ميثود غير معروف» إلا في وقت التشغيل. ولهذا طلبت الوصفة قائمة الميثودات المستعملة في النهاية: قارن تلك القائمة بالوثائق لا الملف كله.
ونقطة ليست كوداً لكنها من صميم هذا الدرس: إن كان بوتك يخزّن رسائل المستخدمين في مكان ما فقل ذلك في رسالة start. فـالأمن السيبراني يبدأ من جمل بهذه البساطة. ولمعرفة كيفية الدفع لكل أداة من إيران، انظر دليل الشراء.

المصادر: Telegram Bot API: authorizing your bot and making requests Telegram: bot features, privacy mode and testing your bot Telegram bots FAQ: broadcasting limits and file sizes Anthropic: supported countries Google: where Gemini Apps are available

حدود هذه النصيحة

هذا الدرس يبلغ ببوت بسيط أول تشغيل له ولا أبعد. وثلاثة أشياء تُركت عمداً ويحتاجها بوت جاد: حفظ حالة المحادثة حين تكون متعددة الخطوات، والدفع داخل البوت، والتوسع حين يراسل بضعة آلاف مستخدم دفعة واحدة. وثلاثتها من شأن الواجهة الخلفية لا من شأن واجهة تيليجرام. وثانياً، الأرقام المذكورة هنا قُرئت من الأسئلة الشائعة الرسمية اليوم وتيليجرام يغيّرها؛ فراجع تلك الصفحة قبل الاتكاء على أي رقم. وثالثاً، لم نقل شيئاً عن الوصول إلى تيليجرام من داخل إيران لأنه ليس لدينا ادعاء يمكن الاستناد إليه؛ وكل ما قسناه هو أن خادمنا نحن يصل إلى api.telegram.org.

من عملنا نحن

الجواب المعروض في القسم الثاني أخذناه اليوم من خادمنا نحن لا نقلناه من مكان. أرسلنا طلباً واحداً إلى https://api.telegram.org/bot123456:FAKE/getMe فكان العائد هذا: {"ok":false,"error_code":401,"description":"Unauthorized"}. وثلاثة أشياء تنتج عن هذا السطر ويمكنك تكرارها كلها. الأول أن الواجهة تعيد ظرف JSON لا صفحة خطأ حتى مع توكن خاطئ، فعلى كودك أن يقرأ ok. والثاني أن رؤية ذلك الجواب لا تحتاج بوتاً أصلاً، أي يمكنك اختبار الاتصال قبل إنشاء واحد. والثالث وهو الأقل راحة: إن كانت سلسلة عشوائية تحصل على هذا الجواب فالسلسلة الصحيحة تحصل على جواب آخر، وهذا بالضبط سبب إلحاح هذا الدرس على مكان التوكن.
ونقطة صغيرة من جانبنا: في هذا الموقع زر التواصل عبر تيليجرام في ملف inc/helpers.php هو رابط t.me، أي آلية الربط العميق نفسها التي تشرحها وثائق البوتات. ولكل بوت أيضاً رابط بصيغة https://t.me/<bot_username> ويمكن إضافة معاملات إليه. وهذه أبسط طريقة لنقل المستخدم من صفحة ويب مباشرة إلى محادثة البوت، وتغفلها معظم المشاريع الجديدة.

اسئلة متابعة حقيقية

أبناء بوت تيليجرام له كلفة؟

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

أيجب أن أعرف البرمجة لبناء بوت؟

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

أيستطيع البوت قراءة رسائل المجموعة؟

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

واصل التعلم