Jak hostować bota node-telegram-bot-api 24/7

Aby hostować bota node-telegram-bot-api 24/7, uruchamiasz go na maszynie, która stale działa: na VPS z Linuksem z usługą systemd, która uruchamia go ponownie, gdy się zatrzyma, albo w planie dla botów w PlayNHost (od 1,99 USD miesięcznie), gdzie panel instaluje twoje pakiety, przekazuje kodowi token i uruchamia bota ponownie po awarii. W naszym teście bot z node-telegram-bot-api 2.3.0 zużył około 63 MB pamięci na Node.js 22. Najpierw jedno: wersja 2, którą npm instaluje dzisiaj, to nowa biblioteka bez klasy TelegramBot, więc poradniki napisane dla starszych wersji już do niej nie pasują. Boty napisane dla 0.x lub 1.x zachowują swoje API, jeśli przypniesz ich wersję, jak pokazano niżej. Kroki w PlayNHost:

1. Na stronie hostingu botów Telegram kliknij Utwórz serwer przy planie. W oknie zamówienia odpowiedz na Na jaką platformę jest Twój bot? wyborem Telegram i wybierz Node.js.
2. Otwórz swój serwer w panelu. Karta Skonfiguruj swojego bota na stronie Przegląd otwiera się na Połącz z Telegramem; jej pierwszy krok, Co działa, powinien pokazywać Ten bot uruchamia Node.js Bot.
3. W Połącz z Telegramem wklej token z @BotFather pod Wklej token swojego bota, kliknij Połącz, sprawdź pokazaną nazwę bota i kliknij Tak, dalej.
4. Sprawdź, czy twój package.json podaje wersję, dla której napisano kod: ^2.3.0 dla bota z new Bot(...) albo starą wersję dla bota z new TelegramBot(...).
5. W Twój kod kliknij Prześlij pliki i prześlij package.json oraz index.js bez node_modules, albo kliknij Połącz Git.
6. Na stronie Bot, w panelu Kod, sprawdź, czy Plik startowy to plik uruchamiający twojego bota (domyślnie index.js). Kliknij Zapisz, jeśli go zmienisz.
7. Kliknij Uruchom bota i otwórz Console. npm instaluje bibliotekę przy pierwszym uruchomieniu, potem twój bot wypisuje Logged in as @your_bot, a znacznik w Przegląd zmienia się na Online w Telegramie.
8. Na stronie Bot, w panelu Telegram, kliknij Otwórz w Telegramie i wyślij swojemu botowi /start.

Tworzenie bota w @BotFather i kroki w panelu opisano w Jak hostować bota Telegram. Ta strona dotyczy samego node-telegram-bot-api: jego wersji, tego, czego używa na serwerze, i tego, co warto wiedzieć przed hostowaniem.

Dla jakiej wersji napisano twojego bota?

Nazwa pakietu została ta sama, ale jego API zmieniło się całkowicie w sierpniu 2026:

README projektu mówi to wprost: "v2 is a from-scratch redesign, no v1 compatibility", a jego changelog mówi, że npm install node-telegram-bot-api wykonane według starego poradnika "now lands you on a completely different API". Bot z TelegramBot uruchomiony z 2.x od razu się wywala, bo tej klasy już nie ma.

Dla bota napisanego dla 0.x zostaw tę wersję w package.json:

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

Zakres z ^ nigdy nie przeskakuje na nową wersję główną, więc codzienna instalacja pakietów na naszych serwerach trzyma twojego bota na 0.x. Nie wpisuj latest ani *. Jeśli instalujesz go zamiast tego przez Pakiety w panelu Kod, wpisz też wersję, node-telegram-bot-api@0.67: nazwa bez wersji prosi npm o wydanie z tagiem latest, czyli 2.3.0.

Co zmierzyliśmy

Jak: na naszym własnym węźle, w jednorazowym kontenerze skonfigurowanym jak plan dla botów 1 GB (obraz Node.js 22 i polecenie startowe naszego typu bota Node.js, z limitem pamięci Node na 80 procent), każdy bot wywołał Telegram z fałszywym tokenem, który Telegram odrzucił. Pamięć to pamięć rezydentna 15 sekund po tej odpowiedzi, czas startu liczy się od uruchomienia do odpowiedzi, a każda wartość to mediana uruchomień od 2 do 4. Mierzyliśmy wersję 2; wersji 0.x nie mierzyliśmy.

To wartości minimalne: bot bez czatów i bez danych. Twój własny kod, to, co trzyma w pamięci, i liczba czatów się do nich dodają, więc biblioteka to mała część planu STARTER o pojemności 0,5 GB.

Minimalny bot z node-telegram-bot-api 2

Odpowiada na /start, czyta token, który daje mu panel, i wypisuje linię gotowości. Umieść oba pliki w głównym folderze bota.

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

Przykłady biblioteki czytają process.env.BOT_TOKEN. Panel przekazuje kodowi token jako TELEGRAM_BOT_TOKEN oraz jako BOT_TOKEN, TOKEN, TELEGRAM_TOKEN i TELOXIDE_TOKEN, więc te przykłady działają bez zmian. run() pochodzi z node-telegram-bot-api/node: odpytuje Telegram i zatrzymuje się czysto po SIGINT lub SIGTERM. Wersja 2 działa z require jak wyżej lub z import.

Jeśli token jest błędny

W naszym teście, z fałszywym tokenem, pierwsze wywołanie wersji 2 do Telegrama (getMe) zakończyło się takim błędem:

TelegramApiError: 401: Unauthorized

Wersja 2 nie ponawia odrzuconego tokena: bot.init() od razu kończy się błędem. Bot powyżej przechwytuje ten przypadek i zamiast tego wypisuje Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., a panel pokazuje baner Telegram nie przyjął tokena twojego bota nad Console. Aby to naprawić, w @BotFather wyślij /mybots, wybierz swojego bota, potem API Token i skopiuj token jeszcze raz. Na stronie Bot, w panelu Telegram, kliknij Zastąp token, wklej go, kliknij Zapisz token, potem Zrestartuj teraz.

Bot 0.x zachowuje się inaczej: nie zatrzymuje się. Loguje linię taką jak error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} i pyta Telegram ponownie mniej więcej co 0,3 sekundy, więc wygląda, jakby działał, choć nic nie odpowiada. Panel czyta tę linię i pokazuje ten sam baner.

Co warto wiedzieć o node-telegram-bot-api na serwerze

• Webhook pozostawiony na bocie: wersja 2 go nie usuwa. Jej odpytywanie traktuje 409 jako konflikt, ponawia 10 razy, co 5 sekund, a potem się zatrzymuje. Bot powyżej wywołuje bot.api.deleteWebhook() przed odpytywaniem; możesz też kliknąć Usuń webhook w panelu Telegram. Wersja 0.x usuwa webhook sama, gdy odpytywanie trafi na 409.
• Inna kopia bota: przy 409 Conflict wersja 2 czeka 5 sekund i po cichu próbuje ponownie, do 10 razy z rzędu. Potem się zatrzymuje, run() wypisuje node-telegram-bot-api: polling stopped on a fatal error: z tekstem od Telegrama, a panel pokazuje Twój bot działa też gdzie indziej. Zatrzymaj kopię na swoim komputerze lub starym hostingu. Zobacz Jak naprawić błąd 409 Conflict bota Telegram.
• Błąd w komendzie nie zatrzymuje bota. Wersja 2 wypisuje Unhandled error while processing update z błędem i działa dalej. Ustaw własną obsługę przez bot.catch((err, ctx) => ...).
• Webhooki: startWebhook, createWebhookServer i webhookCallback wymagają publicznego adresu HTTPS, którego te plany jeszcze nie mają. Użyj run(bot) lub bot.startPolling(). Przenosiny z hostingu z webhookiem: Jak przenieść bota Telegram do PlayNHost.
• Podgląd, co robi: na stronie Bot, w panelu Środowisko, dodaj zmienną DEBUG o wartości node-telegram-bot-api:* (Dodaj zmienną) i uruchom ponownie. Wersja 2 zapisuje wtedy w konsoli każde żądanie i każde odpytanie.
• Wersja Node.js: 2.3.0 wymaga Node.js 18.2 lub nowszego. Runtime w panelu Kod oferuje Node.js 20, 22 (recommended), 24, 25 i 26.
• Limit pamięci: skrypt startowy ustawia NODE_OPTIONS=--max-old-space-size na 80 procent pamięci twojego planu, żeby reszta procesu miała miejsce. Szczegóły skryptu startowego Node.js: Jak hostować bota Discord w Node.js.

Własny hosting na VPS z Linuksem

Wersja 2 wymaga Node.js 18.2 lub nowszego. Na Debianie 12 lub 13 albo Ubuntu 24.04 pakiet dystrybucji jest wystarczająco nowy (Debian 12 dostarcza Node.js 18.20, Debian 13 dostarcza 20.19, Ubuntu 24.04 dostarcza 18.19); Ubuntu 22.04 dostarcza Node.js 12, który jest dla niej za stary:

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

Utwórz użytkownika dla bota, skopiuj pliki i zainstaluj pakiety:

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

Trzymaj token poza kodem, w pliku, który może czytać tylko root:

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

Utwórz /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

Uruchom go teraz i przy każdym starcie systemu, a potem śledź jego wyjście:

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

Restart=always uruchamia bota ponownie po awarii lub po process.exit(1). systemctl stop mybot wysyła SIGTERM, który run() zamienia na czyste zatrzymanie. Najpierw zatrzymaj każdą inną kopię, bo inaczej Telegram odpowie obu przez 409 Conflict.

Własny hosting czy plan dla botów

Na VPS, którym zarządzasz sam, zajmujesz się:

• Aktualizacjami i bezpieczeństwem systemu operacyjnego oraz aktualizacjami Node.js.
• Uruchamianiem npm install po każdej zmianie, plikiem usługi, plikiem tokena i jego uprawnieniami.
• Czytaniem journalctl, żeby sprawdzić, dlaczego bot się zatrzymał.
• Kopiami zapasowymi danych bota.

W zamian VPS uruchomi cokolwiek, a możesz mu dać domenę z HTTPS dla webhooka.

W planie dla botów PlayNHost panel robi to za ciebie:

• Wybór wersji Node.js oraz npm install, gdy zmieni się package.json, plik blokady lub wersja Node.js.
• Token sprawdzany w Telegramie przed zapisem, przechowywany w postaci zaszyfrowanej i przekazywany twojemu kodowi.
• Ponowne uruchomienie bota po awarii. Jeśli zawiedzie znowu w ciągu minuty, zostaje zatrzymany, a Console podaje powód.
• Banery nad Console, które wskazują przyczynę, gdy Telegram odrzuca token, działa inna kopia albo ustawiono webhook, z przyciskiem Usuń webhook w panelu Telegram.
• Przesyłanie plików, wdrożenia z Gita i kopie zapasowe z poziomu panelu.

Pytania, które zadają ludzie

Mój stary bot zatrzymał się z błędem takim jak TelegramBot is not a constructor. Dlaczego?

Najpewniej npm zainstalował wersję 2, która nie ma klasy TelegramBot: require('node-telegram-bot-api') zwraca teraz obiekt z nazwanymi eksportami, takimi jak Bot, a nie klasę, którą można wywołać przez new. Wpisz do package.json wersję, dla której napisano twojego bota, na przykład "node-telegram-bot-api": "^0.67.0", usuń node_modules i package-lock.json w Files i uruchom ponownie: pakiety zainstalują się od nowa. Albo przenieś kod na wersję 2 według tabeli w changelogu projektu.

Czy nowego bota pisać na wersji 2, czy na 0.x?

Nowego bota na wersji 2: to ona dostaje aktualizacje, a 2.3.0 obsługuje Bot API 10.3 Telegrama. Zostań przy 0.x dla istniejącego bota, dopóki nie masz czasu na migrację; nadal instaluje się z npm.

Gdzie sesje przeżywają restart?

Nie w MemorySessionStorage: żyje w procesie i po każdym restarcie jest pusty. FileSessionStorage z node-telegram-bot-api/node zapisuje jeden plik na czat w folderze, który nazwiesz, na przykład ./.my_bot_sessions. W naszych planach ten folder jest w plikach twojego serwera, więc przetrwa restarty i trafia do twoich kopii zapasowych.

Gotowy, by uruchomić swojego bota node-telegram-bot-api na okrągło? Zobacz plany na stronie hostingu botów Telegram.