كيف تستضيف بوت node-telegram-bot-api على مدار الساعة 24/7

لاستضافة بوت node-telegram-bot-api على مدار الساعة 24/7 تشغّله على جهاز يبقى قيد التشغيل دائمًا: خادم VPS بنظام لينكس مع خدمة systemd تعيد تشغيله عند توقفه، أو خطة بوتات لدى PlayNHost (ابتداءً من US$1.99 شهريًا)، حيث تثبّت اللوحة حزمك وتمنح شيفرتك الرمز (token) وتعيد تشغيل البوت إذا تعطل. في اختبارنا استخدم بوت node-telegram-bot-api 2.3.0 نحو 63 MB من الذاكرة على Node.js 22. أمر أولًا: الإصدار 2، وهو ما يثبّته npm اليوم، مكتبة جديدة بلا الفئة TelegramBot، ولذلك لم تعد الشروح المكتوبة للإصدارات الأقدم مطابقة له. تحتفظ البوتات المكتوبة للإصدار 0.x أو 1.x بواجهتها إذا ثبّتَّ إصدارها، كما هو موضح أدناه. الخطوات في PlayNHost:

1. في صفحة استضافة بوتات Telegram، انقر أنشئ سيرفرًا على إحدى الخطط. في نافذة الطلب أجب عن لأي منصة بوتك؟ بـ Telegram واختر Node.js.
2. افتح سيرفرك في اللوحة. تُفتح بطاقة إعداد بوتك في نظرة عامة عند الاتصال بـ Telegram؛ ويجب أن تعرض خطوتها الأولى، ما الذي يعمل، العبارة يشغّل هذا البوت Node.js Bot.
3. عند الاتصال بـ Telegram، الصق الرمز من @BotFather تحت الصق رمز بوتك، وانقر ربط، وتحقق من اسم البوت المعروض، ثم انقر نعم، متابعة.
4. تأكد أن ملف package.json يذكر الإصدار الذي كُتبت له شيفرتك: ^2.3.0 لبوت يستخدم new Bot(...)، أو الإصدار القديم لبوت يستخدم new TelegramBot(...).
5. عند كودك، انقر رفع الملفات وارفع package.json وindex.js دون node_modules، أو انقر ربط Git.
6. في صفحة بوت، قسم الكود، تأكد أن ملف البدء هو الملف الذي يشغّل بوتك (index.js افتراضيًا). انقر حفظ إذا غيّرته.
7. انقر تشغيل البوت وافتح Console. يثبّت npm المكتبة عند أول تشغيل، ثم يطبع بوتك Logged in as @your_bot وتتحول الشارة في نظرة عامة إلى متصل في Telegram.
8. في صفحة بوت، قسم Telegram، انقر افتح في Telegram وأرسل إلى بوتك /start.

إنشاء البوت في @BotFather وخطوات اللوحة موضحة في كيف تستضيف بوت Telegram. تتناول هذه الصفحة node-telegram-bot-api نفسها: إصداراتها، وما تستخدمه على السيرفر، وما يجب أن تعرفه قبل الاستضافة.

لأي إصدار كُتب بوتك؟

بقي اسم الحزمة كما هو، لكن واجهتها تغيّرت بالكامل في أغسطس 2026:

يقول ملف README الخاص بالمشروع ذلك صراحة: "v2 is a from-scratch redesign, no v1 compatibility"، ويقول سجل التغييرات إن تنفيذ npm install node-telegram-bot-api من شرح قديم "now lands you on a completely different API". يفشل بوت TelegramBot المشغَّل على 2.x فورًا، لأن الفئة لم تعد موجودة.

للبوت المكتوب للإصدار 0.x أبقِ ذلك الإصدار في package.json:

"dependencies": {
  "node-telegram-bot-api": "^0.67.0"
}

لا ينتقل النطاق الذي يبدأ بـ ^ إلى إصدار رئيسي جديد أبدًا، ولذلك يُبقي تثبيت الحزم اليومي على سيرفراتنا بوتك على 0.x. لا تكتب latest ولا *. وإذا ثبّتَّها بدلًا من ذلك عبر الحزم في قسم الكود، فاكتب الإصدار أيضًا، node-telegram-bot-api@0.67: الاسم بلا إصدار يطلب من npm الإصدار الموسوم latest، وهو 2.3.0.

ما الذي قسناه

الطريقة: على عقدتنا الخاصة، في حاوية مؤقتة مهيأة مثل خطة بوتات بسعة 1 GB (صورة Node.js 22 وأمر البدء الخاص بنوع بوت Node.js لدينا، مع حد ذاكرة Node عند 80 بالمئة)، استدعى كل بوت Telegram برمز مزيف رفضه Telegram. الذاكرة هي الذاكرة المقيمة بعد 15 ثانية من ذلك الرد، ويُحسب زمن البدء من التشغيل حتى الرد، وكل رقم هو وسيط التشغيلات من 2 إلى 4. قسنا الإصدار 2؛ ولم نقس الإصدار 0.x.

هذه حدود دنيا: بوت بلا محادثات ولا بيانات بعد. تُضاف إليها شيفرتك وما تحتفظ به في الذاكرة وعدد المحادثات، ولذلك تمثل المكتبة جزءًا صغيرًا من خطة STARTER بسعة 0.5 GB.

بوت بسيط بـ node-telegram-bot-api 2

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

package.json

{
  "name": "my-telegram-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "node-telegram-bot-api": "^2.3.0"
  }
}

index.js

const { Bot, TelegramApiError } = require("node-telegram-bot-api");
const { run } = require("node-telegram-bot-api/node");

const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN);

bot.command("start", (ctx) => ctx.reply("Hello! I am running on PlayNHost."));

async function main() {
  await bot.init(); // asks Telegram who the bot is, so a wrong token fails here
  await bot.api.deleteWebhook(); // version 2 does not remove a webhook by itself
  console.log(`Logged in as @${bot.botInfo.username}`);
  await run(bot); // polls for messages until the bot is stopped
}

main().catch((err) => {
  if (err instanceof TelegramApiError && err.errorCode === 401) {
    console.log("Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.");
  } else {
    console.error(err);
  }
  process.exit(1);
});

تقرأ أمثلة المكتبة نفسها process.env.BOT_TOKEN. تمنح اللوحة شيفرتك الرمز باسم TELEGRAM_BOT_TOKEN وكذلك باسم BOT_TOKEN وTOKEN وTELEGRAM_TOKEN وTELOXIDE_TOKEN، ولذلك تعمل تلك الأمثلة دون تعديل. تأتي run() من node-telegram-bot-api/node: تجري الاستطلاع وتتوقف بسلاسة عند SIGINT أو SIGTERM. يعمل الإصدار 2 مع require كما في الأعلى أو مع import.

إذا كان الرمز خاطئًا

في اختبارنا، ومع رمز مزيف، فشل أول استدعاء من الإصدار 2 إلى Telegram (getMe) بهذا الخطأ:

TelegramApiError: 401: Unauthorized

لا يعيد الإصدار 2 المحاولة بالرمز المرفوض: يفشل bot.init() فورًا. يلتقط البوت أعلاه هذه الحالة ويطبع بدلًا من ذلك Telegram did not accept the bot token. Paste the current one from @BotFather, then restart.، وتعرض اللوحة الشريط لم يقبل Telegram رمز بوتك فوق Console. لإصلاح ذلك أرسل في @BotFather الأمر /mybots، واختر بوتك، ثم API Token، وانسخ الرمز مجددًا. في صفحة بوت، قسم Telegram، انقر استبدال الرمز والصقه، وانقر حفظ الرمز، ثم إعادة التشغيل الآن.

يتصرف بوت 0.x بشكل مختلف: لا يتوقف. يسجل سطرًا مثل error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} ويسأل Telegram من جديد كل 0.3 ثانية تقريبًا، فيبدو قيد التشغيل بينما لا شيء يرد. تقرأ اللوحة هذا السطر وتعرض الشريط نفسه.

ما يجب أن تعرفه عن node-telegram-bot-api على السيرفر

• webhook بقي على البوت: لا يزيله الإصدار 2. يعامل استطلاعه الخطأ 409 على أنه تعارض، ويعيد المحاولة 10 مرات بفاصل 5 ثوانٍ، ثم يتوقف. يستدعي البوت أعلاه bot.api.deleteWebhook() قبل الاستطلاع؛ ويمكنك أيضًا النقر على إزالة الـ webhook في قسم Telegram. يزيل الإصدار 0.x الـ webhook بنفسه عندما يصادف الاستطلاع 409.
• نسخة أخرى من البوت: عند 409 Conflict ينتظر الإصدار 2 مدة 5 ثوانٍ ويعيد المحاولة بصمت، حتى 10 مرات متتالية. بعد ذلك يتوقف، وتطبع run() الرسالة node-telegram-bot-api: polling stopped on a fatal error: مع نص Telegram، وتعرض اللوحة بوتك يعمل في مكان آخر أيضًا. أوقف النسخة على حاسوبك أو على استضافتك القديمة. راجع إصلاح خطأ 409 Conflict في بوت Telegram.
• الخطأ في أمر لا يوقف البوت. يطبع الإصدار 2 الرسالة Unhandled error while processing update مع الخطأ ويواصل العمل. اضبط معالجك الخاص بـ bot.catch((err, ctx) => ...).
• Webhooks: تحتاج startWebhook وcreateWebhookServer وwebhookCallback إلى عنوان HTTPS عام، وهذه الخطط لا تتضمنه بعد. استخدم run(bot) أو bot.startPolling(). للانتقال من استضافة تعتمد على webhook: كيف تنقل بوت Telegram إلى PlayNHost.
• رؤية ما يفعله: في صفحة بوت، قسم البيئة، أضف المتغير DEBUG بالقيمة node-telegram-bot-api:* (إضافة متغير) وأعد التشغيل. يسجل الإصدار 2 حينها كل طلب وكل استطلاع في وحدة التحكم.
• إصدار Node.js: يحتاج 2.3.0 إلى Node.js 18.2 أو أحدث. يعرض قسم بيئة التشغيل في الكود الإصدارات Node.js 20 و22 (recommended) و24 و25 و26.
• حد الذاكرة: يضبط سكربت البدء NODE_OPTIONS=--max-old-space-size على 80 بالمئة من ذاكرة خطتك، ليبقى للعملية مجال في بقية الذاكرة. تفاصيل سكربت بدء Node.js: كيف تستضيف بوت Discord بلغة Node.js.

استضفه بنفسك على VPS لينكس

يحتاج الإصدار 2 إلى Node.js 18.2 أو أحدث. على Debian 12 أو 13 أو Ubuntu 24.04 تكون حزمة التوزيعة حديثة بما يكفي (يوفر Debian 12 الإصدار Node.js 18.20، ويوفر Debian 13 الإصدار 20.19، ويوفر Ubuntu 24.04 الإصدار 18.19)؛ أما Ubuntu 22.04 فيوفر Node.js 12، وهو قديم جدًا له:

sudo apt update
sudo apt install nodejs npm
node --version

أنشئ مستخدمًا للبوت وانسخ ملفاتك وثبّت الحزم:

sudo useradd --system --create-home --home-dir /opt/mybot mybot
sudo cp package.json index.js /opt/mybot/
sudo chown -R mybot: /opt/mybot
cd /opt/mybot && sudo -u mybot npm install --omit=dev

أبقِ الرمز خارج شيفرتك، في ملف لا يقرؤه سوى root:

sudo sh -c 'echo "TELEGRAM_BOT_TOKEN=123456789:your-token" > /etc/mybot.env'
sudo chmod 600 /etc/mybot.env

أنشئ الملف /etc/systemd/system/mybot.service:

[Unit]
Description=node-telegram-bot-api Telegram bot
Wants=network-online.target
After=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/usr/bin/node index.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

شغّله الآن وعند كل إقلاع، ثم تابع مخرجاته:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
sudo journalctl -u mybot -f

يعيد Restart=always تشغيل البوت بعد تعطل أو بعد process.exit(1). ويرسل systemctl stop mybot الإشارة SIGTERM التي تحوّلها run() إلى إيقاف سلس. أوقف أي نسخة أخرى أولًا، وإلا ردّ Telegram على النسختين بـ 409 Conflict.

الاستضافة الذاتية أم خطة بوتات

على VPS تديره بنفسك تتولى:

• تحديثات نظام التشغيل وأمانه، وترقيات Node.js.
• تشغيل npm install بعد كل تغيير، وملف الخدمة، وملف الرمز وصلاحياته.
• قراءة journalctl لمعرفة سبب توقف البوت.
• النسخ الاحتياطية لبيانات البوت.

في المقابل يشغّل VPS أي شيء، ويمكنك أن تمنحه نطاقًا مع HTTPS من أجل webhook.

في خطة بوتات PlayNHost تتولى اللوحة ذلك عنك:

• أداة اختيار لإصدار Node.js، وتشغيل npm install عند تغيّر package.json أو ملف القفل أو إصدار Node.js.
• الرمز، يُتحقق منه مع Telegram قبل حفظه، ويُخزَّن مشفرًا ويُسلَّم إلى شيفرتك.
• إعادة تشغيل البوت بعد التعطل. إذا تعطل ثانية خلال دقيقة يبقى متوقفًا وتذكر Console السبب.
• أشرطة فوق Console تسمّي السبب عندما يرفض Telegram الرمز أو تعمل نسخة أخرى أو يكون webhook مضبوطًا، مع زر إزالة الـ webhook في قسم Telegram.
• الرفع ونشر Git والنسخ الاحتياطية من اللوحة.

أسئلة يطرحها الناس

توقف بوتي القديم بخطأ مثل TelegramBot is not a constructor. لماذا؟

على الأرجح ثبّت npm الإصدار 2 الذي لا يملك الفئة TelegramBot: صار require('node-telegram-bot-api') يعيد كائنًا من عناصر مُصدَّرة مسماة مثل Bot، لا فئة يمكنك استدعاؤها بـ new. ضع في package.json الإصدار الذي كُتب له بوتك، مثل "node-telegram-bot-api": "^0.67.0"، واحذف node_modules وpackage-lock.json في Files، ثم أعد التشغيل: تُثبَّت الحزم من جديد. أو انقل الشيفرة إلى الإصدار 2 بالاستعانة بالجدول في سجل تغييرات المشروع.

هل أكتب بوتًا جديدًا على الإصدار 2 أم على 0.x؟

للبوت الجديد، الإصدار 2: فهو الذي يتلقى التحديثات، ويدعم 2.3.0 واجهة Bot API 10.3 من Telegram. أبقِ 0.x للبوت القائم حتى يتسع وقتك للانتقال؛ فما زالت تُثبَّت من npm.

أين تنجو الجلسات من إعادة التشغيل؟

ليس في MemorySessionStorage: فهو يعيش داخل العملية ويكون فارغًا بعد كل إعادة تشغيل. تكتب FileSessionStorage من node-telegram-bot-api/node ملفًا لكل محادثة في مجلد تسميه أنت، مثل ./.my_bot_sessions. في خططنا يقع ذلك المجلد ضمن ملفات سيرفرك، فينجو من إعادة التشغيل ويدخل في نسخك الاحتياطية.

هل أنت مستعد لتشغيل بوت node-telegram-bot-api على مدار الساعة؟ شاهد الخطط في استضافة بوتات Telegram.