إعداد ويب هوك بوت تليجرام: دليل كامل للمطورين

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

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

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

• الويب هوك والاستقصاء الطويل يستبعدان بعضهما البعض. يؤدي تعيين ويب هوك إلى تعطيل getUpdates حتى تقوم بإزالته.
• HTTPS إلزامي. تحتاج نقطة النهاية الخاصة بك إلى TLS 1.2+، وشهادة مطابقة، ومنفذ 443، 80، 88، أو 8443.
• سجل باستخدام setWebhook، وتحقق باستخدام getWebhookInfo. تحقق من last_error_message عندما تتوقف التحديثات عن التدفق.
• استخدم secret_token لتأكيد أن الطلبات تأتي من تليجرام، وليس من الماسحات الضوئية العشوائية التي تضرب عنوان URL الخاص بك.
• بديل بدون كود: يتعامل TeleClaw مع الاستضافة والتسليم بحيث تتخطى طبقة الخادم بالكامل.

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

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

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

يعكس الويب هوك النموذج. يرسل تليجرام طلب HTTPS POST إلى عنوان URL الخاص بك كلما أرسل شخص ما رسالة إلى البوت. هذا يزيل طلبات الاستقصاء الخاملة ويقلل وقت الاستجابة، وهو أمر مهم لبوتات الدعم، وتدفقات الدفع، والإشراف على المجموعات على نطاق واسع.

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

المتطلبات الأساسية لإعداد ويب هوك بوت تليجرام

قبل استدعاء setWebhook، تأكد من أن البنية التحتية الخاصة بك تلبي متطلبات تليجرام من دليل الويب هوك الرسمي:

• رمز البوت من @BotFather (انظر دليل إنشاء البوت المرتبط أعلاه).
• نطاق عام مع شهادة TLS صالحة. تعمل الشهادات ذاتية التوقيع فقط إذا قمت بتحميل المفتاح العام عبر معلمة certificate.
• منفذ مدعوم على خادمك: 443 (افتراضي)، 80، 88، أو 8443. يتم رفض المنافذ الأخرى.
• يجب أن يتطابق CN أو SAN للشهادة مع النطاق في عنوان URL الخاص بالويب هوك. قد لا تعمل شهادات الوايلد كارد. لا يتم دعم عمليات إعادة التوجيه.
• وصول POST الوارد من شبكات تليجرام الفرعية 149.154.160.0/20 و 91.108.4.0/22.

للتطوير المحلي، قم بتعريض localhost من خلال نفق (ngrok، Cloudflare Tunnel، أو ما شابه) يمنحك عنوان URL عامًا لـ HTTPS. اختبر أن النفق يُرجع HTTP 200 لطلبات POST قبل تسجيل الويب هوك.

الخطوة 1: بناء نقطة نهاية الويب هوك الخاصة بك

يحتاج خادمك إلى مسار يقبل طلبات POST، ويحلل كائن Update JSON، ويُرجع HTTP 200 بسرعة. تتسبب المعالجات البطيئة في إعادة محاولة تليجرام وفي النهاية الإبلاغ عن أخطاء في getWebhookInfo.

مثال Node.js بسيط مع Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

يتبع Python مع Flask نفس النمط: قراءة JSON من request، والتحقق من رأس السر إذا تم تكوينه، ومعالجة التحديث، وإرجاع 200.

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

الخطوة 2: تكوين ويب هوك بوت تليجرام باستخدام setWebhook

بمجرد أن تكون نقطة النهاية الخاصة بك مباشرة، سجلها باستخدام Bot API. استبدل <TOKEN> وعنوان URL بقيمك.

باستخدام curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

مرجع المعلمات:

• url (مطلوب): نقطة نهاية HTTPS الخاصة بك. استخدم سلسلة فارغة لإزالة الويب هوك.
• secret_token (اختياري): 1-256 حرفًا (A-Z، a-z، 0-9، _، -). يرسلها تليجرام في رأس X-Telegram-Bot-Api-Secret-Token.
• max_connections (اختياري): 1-100 اتصال متزامن. الافتراضي هو 40.
• allowed_updates (اختياري): حدد أنواع التحديثات التي تتلقاها. يقلل حجم الحمولة إذا كنت تتعامل مع الرسائل فقط.
• drop_pending_updates (اختياري): اضبط true لتجاهل التحديثات المعلقة عند تبديل الويب هوك.
• certificate (اختياري): قم بتحميل ملف المفتاح العام الخاص بك للشهادات ذاتية التوقيع.

تبدو الاستجابة الناجحة كالتالي: {"ok":true,"result":true,"description":"Webhook was set"}.

الخطوة 3: التحقق باستخدام getWebhookInfo

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

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

مثال على الاستجابة:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

راقب هذه الحقول:

• url: فارغ يعني عدم وجود ويب هوك نشط (البوت يعمل بالاستقصاء الطويل).
• pending_update_count: التحديثات المعلقة في قائمة الانتظار بانتظار التسليم. يشير العدد المتزايد إلى فشل التسليم.
• last_error_date و last_error_message: أحدث سبب للفشل. قم بإصلاح السبب الجذري، ثم يعيد تليجرام المحاولة تلقائيًا.
• ip_address: أي IP من تليجرام يضرب نقطة النهاية الخاصة بك حاليًا.

أرسل رسالة اختبار إلى البوت الخاص بك من حساب تليجرام حقيقي. إذا ظل pending_update_count عند الصفر وأظهرت سجلات الخادم الخاص بك POST، فإن إعداد ويب هوك بوت تليجرام يعمل.

مثال على ويب هوك بوت تليجرام: معالج طلب الانضمام

تحتاج بوتات طلب الانضمام (تدفقات القبول على غرار Guardian) إلى نوع التحديث chat_join_request. يغطي دليل بوت Guardian الجانب المنتج. إليك توصيل الويب هوك.

سجل مع تمكين طلبات الانضمام:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

منطق المعالج (شبه كود):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // قم بتشغيل منطق الفحص، ثم وافق أو ارفض عبر Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

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

إزالة ويب هوك بوت تليجرام والعودة إلى الاستقصاء

هل تحتاج إلى تصحيح الأخطاء محليًا باستخدام getUpdates؟ قم بإزالة الويب هوك أولاً.

الخيار أ مع deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

الخيار ب مع setWebhook وعنوان URL فارغ:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

تعيد كلتا الطريقتين تمكين الاستقصاء الطويل. إذا تخطيت هذه الخطوة، فإن getUpdates لا يُرجع شيئًا لأن الويب هوك لا يزال مسجلاً لعنوان URL الإنتاجي الخاص بك.

استكشاف أخطاء الويب هوك الشائعة وإصلاحها

عندما يُظهر getWebhookInfo أخطاء، قم بمطابقة الرسالة مع حل:

شغّل getWebhookInfo بانتظام في الإنتاج. اكتشاف last_error_message مبكرًا يمنع ساعات من فقدان الرسائل الصامت.

تخطي الخادم: بوتات مُدارة مع TeleClaw

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

يربط TeleClaw رمز BotFather الخاص بك بوقت تشغيل مُدار مدعوم من OpenClaw. يمكنك تكوين الشخصية وقاعدة المعرفة وقواعد الإشراف في لوحة التحكم. تتعامل المنصة مع نقاط نهاية HTTPS، والتوسع، وتوجيه نموذج الذكاء الاصطناعي. أضف @claw كمسؤول مجموعة وابدأ العمل دون كتابة معالج ويب هوك.

استكشف ما يمكن أن يفعله البوت المُدار في صفحة ميزات TeleClaw. للحصول على دليل كامل بدون كود، راجع دليل بوت تليجرام بدون كود.

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

الخلاصة

يتم إعداد ويب هوك بوت تليجرام في أربع خطوات: نشر نقطة نهاية HTTPS، استدعاء setWebhook، التحقق باستخدام getWebhookInfo، ومراقبة الأخطاء. استخدم secret_token للتحقق من الطلبات، وحدد allowed_updates لما تقوم بمعالجته، واجعل المعالجات سريعة.

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

هل أنت مستعد لإطلاق بوت ذكاء اصطناعي دون إدارة الويب هوك؟ أضف @claw إلى مجموعة تليجرام الخاصة بك ←