node-telegram-bot-api botu 24/7 nasıl barındırılır

Bir node-telegram-bot-api botunu 24/7 barındırmak için onu hep açık kalan bir makinede çalıştırırsınız: durduğunda botu yeniden başlatan bir systemd hizmetiyle Linux VPS ya da PlayNHost üzerinde bir bot planı (ayda US$1,99’dan başlar). Bot planında panel paketlerinizi kurar, token’ı koduna verir ve bot çökerse yeniden başlatır. Testimizde node-telegram-bot-api 2.3.0 kullanan bir bot, Node.js 22 üzerinde yaklaşık 63 MB bellek kullandı. Önce bir şey: npm’in bugün kurduğu 2. sürüm, TelegramBot sınıfı olmayan yeni bir kütüphanedir; bu yüzden eski sürümler için yazılmış eğitimler artık uymaz. 0.x veya 1.x için yazılmış botlar, sürümlerini aşağıda gösterildiği gibi sabitlerseniz API’lerini korur. PlayNHost’taki adımlar:

1. Telegram bot barındırma sayfasında bir planın üzerinde Sunucu oluştur düğmesine tıklayın. Sipariş penceresinde Botunuz hangi platform için? sorusunu Telegram ile yanıtlayın ve Node.js seçin.
2. Sunucunuzu panelde açın. Genel bakış sayfasındaki Botunuzu kurun kartı Telegram’a bağlan adımında açılır; ilk adımı olan Ne çalışır şunu göstermelidir: Bu bot Node.js Bot çalıştırır.
3. Telegram’a bağlan bölümünde @BotFather’dan aldığınız token’ı Bot token’ınızı yapıştırın alanına yapıştırın, Bağlan düğmesine tıklayın, gösterilen bot adını kontrol edin ve Evet, devam düğmesine tıklayın.
4. package.json dosyanızın kodunuzun yazıldığı sürümü gösterdiğini kontrol edin: ^2.3.0 değeri new Bot(...) kullanan bir bot için, eski sürüm ise new TelegramBot(...) kullanan bir bot için.
5. Kodunuz bölümünde Dosya yükle düğmesine tıklayıp package.json ve index.js dosyalarınızı node_modules olmadan yükleyin ya da Git’i bağla düğmesine tıklayın.
6. Bot sayfasında Kod bölümünde Giriş dosyası alanının botunuzu başlatan dosya olduğunu kontrol edin (varsayılan index.js). Değiştirirseniz Kaydet düğmesine tıklayın.
7. Botu başlat düğmesine tıklayın ve Console bölümünü açın. npm kütüphaneyi ilk başlatmada kurar, ardından botunuz Logged in as @your_bot yazdırır ve Genel bakış sayfasındaki etiket Telegram’da çevrimiçi olur.
8. Bot sayfasında Telegram bölümünde Telegram’da aç düğmesine tıklayın ve botunuza /start gönderin.

Botu @BotFather’da oluşturma ve panel adımları Telegram botu nasıl barındırılır yazısında anlatılıyor. Bu sayfa node-telegram-bot-api’nin kendisini ele alır: sürümlerini, bir sunucuda neyi kullandığını ve barındırmadan önce bilmeniz gerekenleri.

Botunuz hangi sürüm için yazıldı?

Paket adı aynı kaldı, ancak API’si Ağustos 2026’da tamamen değişti:

Projenin README dosyası bunu açıkça söylüyor: "v2 is a from-scratch redesign, no v1 compatibility", changelog’u ise eski bir eğitimden yapılan npm install node-telegram-bot-api komutunun sizi "now lands you on a completely different API" durumuna getirdiğini yazıyor. 2.x ile başlatılan bir TelegramBot botu hemen hata verir, çünkü sınıf artık yok.

0.x için yazılmış bir botta bu sürümü package.json içinde tutun:

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

^ aralığı hiçbir zaman yeni bir ana sürüme geçmez; bu yüzden sunucularımızdaki günlük paket kurulumu botunuzu 0.x’te tutar. latest veya * yazmayın. Bunun yerine Kod bölümündeki Paketler üzerinden kurarsanız sürümü de yazın, node-telegram-bot-api@0.67: sürümsüz bir ad npm’den latest etiketli sürümü ister, o da 2.3.0’dır.

Ne ölçtük

Nasıl: kendi node’umuzda, 1 GB’lık bir bot planı gibi ayarlanmış tek kullanımlık bir konteynerde (Node.js 22 imajı ve Node.js bot türümüzün başlatma komutu, Node’un bellek sınırı yüzde 80’de), her bot Telegram’ı sahte bir token ile çağırdı ve Telegram bunu reddetti. Bellek, bu yanıttan 15 saniye sonraki resident bellektir, başlangıç süresi başlatmadan yanıta kadar geçen süredir ve her değer 2. ile 4. çalıştırmaların medyanıdır. 2. sürümü ölçtük; 0.x ölçülmedi.

Bunlar alt sınırlardır: henüz sohbeti ve verisi olmayan bir bot. Kendi kodunuz, bellekte tuttukları ve sohbet sayısı bunlara eklenir; bu yüzden kütüphane, 0,5 GB’lık STARTER planının küçük bir parçasıdır.

node-telegram-bot-api 2 ile minimal bir bot

/start komutunu yanıtlar, panelin verdiği token’ı okur ve bir hazır satırı yazdırır. İki dosyayı da botunuzun ana klasörüne koyun.

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);
});

Kütüphanenin kendi örnekleri process.env.BOT_TOKEN değerini okur. Panel koduna token’ı TELEGRAM_BOT_TOKEN olarak ve ayrıca BOT_TOKEN, TOKEN, TELEGRAM_TOKEN ve TELOXIDE_TOKEN olarak verir; bu yüzden o örnekler değişiklik yapmadan çalışır. run(), node-telegram-bot-api/node içinden gelir: yoklama yapar ve SIGINT ya da SIGTERM geldiğinde temiz biçimde durur. 2. sürüm, yukarıdaki gibi require ile de import ile de çalışır.

Token yanlışsa

Testimizde, sahte bir token ile 2. sürümün Telegram’a ilk çağrısı (getMe) şu hatayla başarısız oldu:

TelegramApiError: 401: Unauthorized

2. sürüm reddedilen bir token’ı yeniden denemez: bot.init() hemen hata verir. Yukarıdaki bot bu durumu yakalar ve onun yerine Telegram did not accept the bot token. Paste the current one from @BotFather, then restart. yazdırır; panel de Console üzerinde Telegram bot token’ınızı kabul etmedi bandını gösterir. Düzeltmek için @BotFather’da /mybots gönderin, botunuzu seçin, ardından API Token seçeneğini seçip token’ı yeniden kopyalayın. Bot sayfasında Telegram bölümünde Token’ı değiştir düğmesine tıklayın, token’ı yapıştırın, Token’ı kaydet düğmesine, ardından Şimdi yeniden başlat düğmesine tıklayın.

0.x botu farklı davranır: durmaz. error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} gibi bir satır kaydeder ve Telegram’a yaklaşık her 0,3 saniyede bir yeniden sorar; böylece hiçbir şey yanıt vermezken çalışıyor gibi görünür. Panel bu satırı okur ve aynı bandı gösterir.

node-telegram-bot-api’nin bir sunucuda bilmeniz gerekenleri

• Botta kalmış bir webhook: 2. sürüm onu kaldırmaz. Yoklaması 409 hatasını bir çakışma olarak ele alır, 5 saniye arayla 10 kez yeniden dener, sonra durur. Yukarıdaki bot, yoklamadan önce bot.api.deleteWebhook() çağırır; Telegram bölümünde Webhook’u kaldır düğmesine de tıklayabilirsiniz. 0.x sürümü, yoklama bir 409 ile karşılaştığında webhook’u kendisi kaldırır.
• Botun başka bir kopyası: 409 Conflict durumunda 2. sürüm 5 saniye bekler ve sessizce yeniden dener, üst üste 10 kereye kadar. Ardından durur, run() Telegram’ın metniyle birlikte node-telegram-bot-api: polling stopped on a fatal error: yazdırır ve panel Botunuz başka bir yerde de çalışıyor bandını gösterir. Bilgisayarınızdaki ya da eski barındırıcınızdaki kopyayı durdurun. Bkz. Telegram botu 409 Conflict hatasını düzeltin.
• Bir komuttaki hata botu durdurmaz. 2. sürüm hatayla birlikte Unhandled error while processing update yazdırır ve devam eder. Kendi işleyicinizi bot.catch((err, ctx) => ...) ile ayarlayın.
• Webhook’lar: startWebhook, createWebhookServer ve webhookCallback herkese açık bir HTTPS adresi gerektirir; bu planlarda henüz yok. run(bot) veya bot.startPolling() kullanın. Webhook kullanan bir barındırıcıdan taşınma: Telegram botunuzu PlayNHost’a nasıl taşırsınız.
• Ne yaptığını görmek: Bot sayfasında Ortam bölümünde DEBUG değişkenini node-telegram-bot-api:* değeriyle ekleyin (Değişken ekle) ve yeniden başlatın. 2. sürüm bunun ardından her isteği ve her yoklamayı konsola yazar.
• Node.js sürümü: 2.3.0, Node.js 18.2 veya daha yenisini gerektirir. Kod bölümündeki Çalışma ortamı Node.js 20, 22 (recommended), 24, 25 ve 26 sunar.
• Bellek sınırı: başlatma betiği, sürecin geri kalanına yer kalsın diye NODE_OPTIONS=--max-old-space-size değerini planınızın belleğinin yüzde 80’ine ayarlar. Node.js başlatma betiğinin ayrıntıları: Node.js Discord botu nasıl barındırılır.

Kendiniz bir Linux VPS’te barındırın

2. sürüm Node.js 18.2 veya daha yenisini gerektirir. Debian 12 veya 13’te ya da Ubuntu 24.04’te dağıtımın paketi yeterince yenidir (Debian 12 Node.js 18.20, Debian 13 20.19, Ubuntu 24.04 18.19 sunar); Ubuntu 22.04 Node.js 12 sunar, bu da onun için fazla eskidir:

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

Bot için bir kullanıcı oluşturun, dosyalarınızı kopyalayın ve paketleri kurun:

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

Token’ı kodunuzdan uzak tutun, yalnızca root’un okuyabileceği bir dosyada saklayın:

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

/etc/systemd/system/mybot.service dosyasını oluşturun:

[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

Hemen ve her açılışta başlatın, ardından çıktısını izleyin:

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

Restart=always, bir çökmeden veya process.exit(1) çağrısından sonra botu yeniden başlatır. systemctl stop mybot SIGTERM gönderir ve run() bunu temiz bir duruşa çevirir. Önce başka her kopyayı durdurun; yoksa Telegram ikisine de 409 Conflict ile yanıt verir.

Kendi barındırmanız mı, bot planı mı

Kendinizin yönettiği bir VPS’te şunlarla siz ilgilenirsiniz:

• İşletim sistemi güncellemeleri ve güvenliği ile Node.js yükseltmeleri.
• Her değişiklikten sonra npm install çalıştırmak, hizmet dosyası, token dosyası ve izinleri.
• Botun neden durduğunu anlamak için journalctl okumak.
• Botun verilerinin yedekleri.

Karşılığında bir VPS her şeyi çalıştırır ve ona bir webhook için HTTPS’li bir alan adı verebilirsiniz.

PlayNHost bot planında bunları panel sizin için yapar:

• Bir Node.js sürüm seçici; npm install da package.json, kilit dosyası ya da Node.js sürümü değiştiğinde çalışır.
• Kaydedilmeden önce Telegram ile kontrol edilen, şifreli saklanan ve koduna verilen token.
• Çökmeden sonra botun yeniden başlatılması. Bir dakika içinde yine çökerse durmuş kalır ve Console nedenini söyler.
• Telegram token’ı reddettiğinde, başka bir kopya çalıştığında veya bir webhook ayarlı olduğunda nedeni söyleyen, Console üzerindeki bantlar; Telegram bölümünde bir Webhook’u kaldır düğmesiyle birlikte.
• Panelden yükleme, Git ile dağıtım ve yedekler.

İnsanların sorduğu sorular

Eski botum TelegramBot is not a constructor gibi bir hatayla durdu. Neden?

Büyük olasılıkla npm, TelegramBot sınıfı olmayan 2. sürümü kurdu: require('node-telegram-bot-api') artık Bot gibi adlandırılmış dışa aktarımlardan oluşan bir nesne döndürür; new ile çağırabileceğiniz bir sınıf değildir. Botunuzun yazıldığı sürümü package.json içine yazın, örneğin "node-telegram-bot-api": "^0.67.0", node_modules ve package-lock.json dosyalarını Files bölümünde silin ve yeniden başlatın: paketler yeniden kurulur. Ya da kodu projenin changelog’undaki tabloyla 2. sürüme taşıyın.

Yeni bir botu 2. sürümde mi yazmalıyım, 0.x’te mi?

Yeni bir bot için 2. sürüm: güncelleme alan odur ve 2.3.0, Telegram’ın Bot API 10.3 sürümünü destekler. Mevcut bir bot için taşımaya vaktiniz olana kadar 0.x’te kalın; hâlâ npm’den kurulur.

Oturumlar yeniden başlatmadan nerede sağ çıkar?

MemorySessionStorage içinde değil: o süreçte yaşar ve her yeniden başlatmadan sonra boştur. FileSessionStorage (node-telegram-bot-api/node içinden), her sohbet için adını verdiğiniz bir klasöre, örneğin ./.my_bot_sessions, bir dosya yazar. Planlarımızda bu klasör sunucunuzun dosyalarındadır; bu yüzden yeniden başlatmalardan sağ çıkar ve yedeklerinizde yer alır.

node-telegram-bot-api botunuzu günün her saati çalıştırmaya hazır mısınız? Planları Telegram bot barındırma sayfasında görün.