دليلك الشامل لإنشاء أول بوت تيليجرام باستخدام Bot API

أسرع طريقة لتعلم Telegram Bot API هي من خلال ثلاثة أوامر بسيطة: احصل على توكن من BotFather، استدعِ getUpdates لقراءة الرسائل، واستدعِ sendMessage للرد. كل ما عدا ذلك في تطوير البوتات يبنى على هذه الحلقة الأساسية. يرشدك هذا الدليل عبر المسار الكامل، من أول طلب cURL إلى بوت يعمل بكامل طاقته مع ويب هوك ومكتبة برمجية.

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

بحلول نهاية هذا الدليل، ستفهم كيفية مصادقة API للطلبات، وكيفية استقبال وإرسال الرسائل، والفرق بين الاستقصاء الطويل (long polling) والويب هوكس (webhooks)، وحدود السرعة التي تعيق معظم البوتات الأولى.

النقاط الرئيسية

• البوت هو مجرد عميل HTTP. كل دالة هي طلب إلى https://api.telegram.org/bot<TOKEN>/METHOD_NAME، لذا فإن cURL كافٍ للبدء.
• ثلاث دوال أساسية تجعلك تبدأ: getMe للتحقق من التوكن، getUpdates لقراءة الرسائل، وsendMessage للرد.
• الاستقصاء الطويل والويب هوكس يستبعدان بعضهما البعض. استخدم الاستقصاء للاختبار المحلي، وانتقل إلى الويب هوك للإنتاج.
• الـ API مجاني، لكن تيليجرام يحدد إرسال الرسائل بكميات كبيرة بحوالي 30 رسالة في الثانية لمستخدمين مختلفين، ورسالة واحدة في الثانية لكل محادثة.
• المكتبة البرمجية توفر الوقت بمجرد أن يتجاوز البوت كونه مجرد سكريبت. استخدم python-telegram-bot أو aiogram أو Telegraf.

ما هو Telegram Bot API؟

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

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

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

الخطوة 1: احصل على توكن بوت من BotFather

افتح تيليجرام وابحث عن @BotFather، البوت الرسمي لإنشاء وإدارة البوتات الأخرى. ابدأ محادثة وأرسل الأمر /newbot.

يسألك BotFather بعد ذلك عن شيئين بالترتيب:

1. اسم عرض لبوتك، مثل “أول بوت API”.
2. اسم مستخدم ينتهي بـ bot، مثل first_api_demo_bot.

عند الانتهاء، يعيد BotFather توكن API يبدو كـ 123456789:AAExampleTokenStringHere. هذا التوكن هو الاعتماد الوحيد الذي تحتاجه لبقية هذا الدليل.

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

الخطوة 2: استدعِ أول دالة Bot API

قبل كتابة أي برنامج، تأكد من أن التوكن يعمل. تعيد دالة getMe معلومات أساسية عن بوتك وهي الفحص القياسي للصحة. استبدل <YOUR_TOKEN> بالقيمة التي حصلت عليها من BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

الاستجابة الناجحة هي JSON مع "ok": true ومعرف بوتك واسمه واسم المستخدم. إذا رأيت "ok": false، فالتوكن خاطئ أو به خطأ إملائي.

هذا الطلب الواحد هو النمط بأكمله. تتبع كل دالة من دوال Telegram Bot API نفس الشكل: استدعاء HTTPS إلى https://api.telegram.org/bot<TOKEN>/METHOD_NAME، مع معلمات في سلسلة الاستعلام أو نص POST، وكائن JSON في المقابل. القائمة الكاملة موجودة في مرجع Bot API، والذي يوثق كل دالة وكائن ستحتاجه على الإطلاق.

الخطوة 3: استقبال وإرسال الرسائل

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

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

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

في الاستجابة، ابحث عن message.chat.id. هذا chat_id هو العنوان الذي ترد عليه. انسخه، ثم استدعِ sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="مرحباً من بوتي الأول"

يرد بوتك في المحادثة. هذه الرحلة ذهابًا وإيابًا، القراءة باستخدام getUpdates والرد باستخدام sendMessage، هي الحلقة الأساسية وراء معظم بوتات تيليجرام. يقبل المعامل text ما يصل إلى 4096 حرفًا لكل رسالة، لذا يجب تقسيم الردود الطويلة.

تفصيلان يجب تذكرهما عند توسيع مثال Telegram Bot API هذا إلى كود حقيقي:

• أعد حساب الإزاحة (offset). مرر update_id آخر تحديث مضافًا إليه واحد كمعامل offset في استدعاء getUpdates التالي، وإلا سيستمر تيليجرام في إعادة نفس التحديثات.
• دالة واحدة في كل مرة. تتوقف getUpdates عن العمل بمجرد تسجيل ويب هوك، وهو موضوع الخطوة التالية.

الخطوة 4: اختر الاستقصاء الطويل أو الويب هوك

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

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

للتبديل إلى ويب هوك، سجل عنوان URL العام الخاص بك مرة واحدة:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

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

الخطوة 5: تغليف الـ API في مكتبة برمجية

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

اختر حسب اللغة التي تعرفها بالفعل:

• Python: python-telegram-bot هي بايثون خالصة، غير متزامنة بالكامل، وتدعم بايثون 3.10 وما فوق. aiogram وpyTelegramBotAPI بدائل شائعة.
• Node.js: Telegraf ناضجة ومتوافقة مع TypeScript. node-telegram-bot-api خيار قديم.

إليك نفس بوت الصدى (echo bot) بلغة بايثون، وهي نقطة البداية الأكثر شيوعًا لدليل Telegram Bot API Python:

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

وما يعادله في Node.js باستخدام Telegraf:

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

كلاهما يؤدي نفس وظيفة حلقة cURL من الخطوة 3، ولكن في بضعة أسطر ومع التعامل مع الأجزاء المعقدة نيابة عنك. انتقلت ماريا، مطورة الواجهة الخلفية التي كانت تقوم بإنشاء بوت دعم، من اختبارات cURL إلى python-telegram-bot في فترة ما بعد الظهر، وكان لديها معالجات الأوامر والأزرار المضمنة تعمل في نفس اليوم. انتقلت مفاهيم API مباشرة لأن المكتبة هي غلاف رفيع لنفس طرق HTTP.

حدود السرعة والحصص التي يجب معرفتها

الـ API مجاني، لكنه ليس بلا حدود. يسرد الأسئلة الشائعة حول البوتات من تيليجرام الإرشادات التي تمنع بوتك من التعرض للتقييد.

• رسالة واحدة في الثانية لكل محادثة. في محادثة واحدة، تجنب الإرسال أسرع من ذلك.
• حوالي 30 رسالة في الثانية إجمالاً عند الإرسال إلى العديد من المستخدمين المختلفين. تجاوز هذا الحد وستبدأ في تلقي استجابات HTTP 429 “Too Many Requests”.
• حوالي 20 رسالة في الدقيقة لنفس المجموعة.

عندما يتطلب البث حقًا المزيد، يمكنك تمكين البث المدفوع (Paid Broadcasts) في @BotFather، مما يرفع السقف إلى 1000 رسالة في الثانية. تكلف الرسائل التي تتجاوز الـ 30 رسالة المجانية في الثانية 0.1 نجمة تيليجرام لكل منها. معظم البوتات لا تحتاج إلى هذا أبدًا، ولكن من الجيد معرفة وجود هذا الحد قبل تصميم ميزة إشعارات.

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

تخطى الكود: بوتات الذكاء الاصطناعي بدون خادم

لا يحتاج كل مشروع إلى قاعدة كود مخصصة. إذا كان هدفك هو مساعد ذكاء اصطناعي في مجموعة تيليجرام، فإن Bot API هو مجرد بنية تحتية قد لا ترغب في صيانتها بنفسك، خاصة طبقة الاستضافة وHTTPS والويب هوك.

TeleClaw هي منصة بدون كود تشغل البوت نيابة عنك وتربط Claude AI مباشرة. ما عليك سوى إضافة @claw إلى مجموعتك، ولصق توكن BotFather الخاص بك في لوحة التحكم، وتكوين السلوك دون الحاجة إلى لمس setWebhook أو التعامل مع حدود السرعة. توماس، الذي يدير مجتمع عملات مشفرة يضم 4000 عضو، استبدل بوتًا مخصصًا غير مكتمل بـ TeleClaw، وكان لديه إشراف بالذكاء الاصطناعي وإجابات للأسئلة الشائعة تعمل في نفس المساء.

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

الخلاصة

لديك الآن نموذج ذهني عملي لـ Telegram Bot API: توكن من BotFather، دوال HTTP مثل getMe وgetUpdates وsendMessage، خيار بين الاستقصاء الطويل والويب هوكس، ومكتبة لتغليف كل ذلك بمجرد أن يكبر بوتك. الـ API مجاني، موثق جيدًا، وسهل الاستخدام بما يكفي للاختبار باستخدام cURL في دقائق.

أسرع خطوة تالية هي الأصغر. افتح @BotFather، قم بتشغيل /newbot، وأرسل أول طلب getMe لتأكيد التوكن. من هناك يمكنك البناء بلغة بايثون أو Node، أو تخطي الخادم بالكامل. لإطلاق بوت يعمل بالذكاء الاصطناعي في دقائق بدلاً من أيام، أضف @claw إلى مجموعتك وقم بتكوينه في لوحة تحكم TeleClaw.