Como hospedar um bot node-telegram-bot-api 24/7

Para hospedar um bot node-telegram-bot-api 24/7, você o executa em uma máquina que fica sempre ligada: uma VPS Linux com um serviço systemd que o inicia de novo quando ele para, ou um plano de bots na PlayNHost (a partir de US$1,99 por mês), em que o painel instala seus pacotes, entrega o token ao seu código e inicia o bot de novo se ele travar. No nosso teste, um bot com node-telegram-bot-api 2.3.0 usou cerca de 63 MB de memória no Node.js 22. Uma coisa antes: a versão 2, a que o npm instala hoje, é uma biblioteca nova sem a classe TelegramBot, então os tutoriais escritos para versões anteriores não servem mais. Bots escritos para 0.x ou 1.x mantêm a API se você fixar a versão deles, como mostrado abaixo. Os passos na PlayNHost:

1. Em hospedagem de bots do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda a Para qual plataforma é o seu bot? com Telegram e escolha Node.js.
2. Abra seu servidor no painel. O cartão Configurar seu bot em Visão geral abre em Conectar ao Telegram; o primeiro passo, O que roda, deve dizer Este bot roda Node.js Bot.
3. Em Conectar ao Telegram, cole o token do @BotFather em Cole o token do seu bot, clique em Conectar, confira o nome do bot exibido e clique em Sim, continuar.
4. Confira se o seu package.json indica a versão para a qual seu código foi escrito: ^2.3.0 para um bot com new Bot(...), ou a versão antiga para um bot com new TelegramBot(...).
5. Em Seu código, clique em Enviar arquivos e envie seu package.json e index.js sem node_modules, ou clique em Conectar o Git.
6. Na página Bot, painel Código, confira se Arquivo de entrada é o arquivo que inicia seu bot (index.js por padrão). Clique em Salvar se você mudar.
7. Clique em Iniciar bot e abra Console. O npm instala a biblioteca na primeira inicialização, depois seu bot imprime Logged in as @your_bot e o indicador em Visão geral muda para Online no Telegram.
8. Na página Bot, painel Telegram, clique em Abrir no Telegram e envie /start ao seu bot.

A criação do bot no @BotFather e os passos do painel são explicados em Como hospedar um bot do Telegram. Esta página trata do node-telegram-bot-api em si: suas versões, o que ele usa em um servidor e o que você deve saber antes de hospedá-lo.

Para qual versão o seu bot foi escrito?

O nome do pacote continuou o mesmo, mas a API mudou por completo em agosto de 2026:

O README do projeto diz isso com clareza: "v2 is a from-scratch redesign, no v1 compatibility", e o changelog diz que npm install node-telegram-bot-api feito a partir de um tutorial antigo "now lands you on a completely different API". Um bot com TelegramBot iniciado com a 2.x falha na hora, porque a classe não existe mais.

Para um bot escrito para 0.x, mantenha essa versão no package.json:

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

Um intervalo com ^ nunca pula para uma nova versão maior, então a instalação diária de pacotes nos nossos servidores mantém seu bot na 0.x. Não escreva latest nem *. Se você instalar por Pacotes no painel Código, escreva a versão também, node-telegram-bot-api@0.67: um nome sem versão pede ao npm a versão com a tag latest, que é a 2.3.0.

O que medimos

Como: no nosso próprio nó, em um contêiner descartável configurado como um plano de bots de 1 GB (a imagem do Node.js 22 e o comando de inicialização do nosso tipo de bot Node.js, com o limite de memória do Node em 80 por cento), cada bot chamou o Telegram com um token falso, que o Telegram recusou. A memória é a memória residente 15 segundos depois dessa resposta, o tempo de início vai da execução até a resposta, e cada valor é a mediana das execuções 2 a 4. Medimos a versão 2; a 0.x não foi medida.

São valores mínimos: um bot sem chats e sem dados ainda. Seu próprio código, o que ele guarda na memória e o número de chats se somam a eles, então a biblioteca é uma parte pequena do plano STARTER de 0,5 GB.

Um bot mínimo com node-telegram-bot-api 2

Ele responde a /start, lê o token que o painel entrega e imprime uma linha de pronto. Coloque os dois arquivos na pasta principal do seu bot.

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

Os exemplos da biblioteca leem process.env.BOT_TOKEN. O painel entrega o token ao seu código como TELEGRAM_BOT_TOKEN e também como BOT_TOKEN, TOKEN, TELEGRAM_TOKEN e TELOXIDE_TOKEN, então esses exemplos rodam sem alterações. run() vem de node-telegram-bot-api/node: ele faz polling e para de forma limpa com SIGINT ou SIGTERM. A versão 2 funciona com require, como acima, ou com import.

Se o token estiver errado

No nosso teste, com um token falso, a primeira chamada da versão 2 ao Telegram (getMe) falhou com este erro:

TelegramApiError: 401: Unauthorized

A versão 2 não tenta de novo um token recusado: bot.init() falha na hora. O bot acima captura esse caso e imprime no lugar Telegram did not accept the bot token. Paste the current one from @BotFather, then restart., e o painel mostra o aviso O Telegram não aceitou o token do seu bot acima de Console. Para corrigir, no @BotFather envie /mybots, escolha seu bot, depois API Token, e copie o token de novo. Na página Bot, painel Telegram, clique em Substituir token, cole-o, clique em Salvar token e depois em Reiniciar agora.

Um bot 0.x se comporta de forma diferente: ele não para. Ele registra uma linha como error: [polling_error] {"code":"ETELEGRAM","message":"ETELEGRAM: 401 Unauthorized"} e pergunta ao Telegram de novo a cada 0,3 segundo, mais ou menos, então parece estar rodando enquanto nada responde. O painel lê essa linha e mostra o mesmo aviso.

O que saber sobre o node-telegram-bot-api em um servidor

• Um webhook que ficou no bot: a versão 2 não o remove. O polling dela trata o 409 como um conflito, tenta de novo 10 vezes, com 5 segundos de intervalo, e depois para. O bot acima chama bot.api.deleteWebhook() antes de fazer polling; você também pode clicar em Remover webhook no painel Telegram. A versão 0.x remove um webhook sozinha quando o polling encontra um 409.
• Outra cópia do bot: em um 409 Conflict, a versão 2 espera 5 segundos e tenta de novo, em silêncio, até 10 vezes seguidas. Depois disso ela para, run() imprime node-telegram-bot-api: polling stopped on a fatal error: com o texto do Telegram, e o painel mostra Seu bot também está rodando em outro lugar. Pare a cópia no seu PC ou na sua hospedagem antiga. Veja Como corrigir o erro 409 Conflict do bot do Telegram.
• Um erro em um comando não para o bot. A versão 2 imprime Unhandled error while processing update com o erro e continua. Defina seu próprio tratador com bot.catch((err, ctx) => ...).
• Webhooks: startWebhook, createWebhookServer e webhookCallback precisam de um endereço HTTPS público, que estes planos ainda não incluem. Use run(bot) ou bot.startPolling(). Para sair de uma hospedagem com webhook: Como migrar um bot do Telegram para a PlayNHost.
• Ver o que ele faz: na página Bot, painel Ambiente, adicione a variável DEBUG com o valor node-telegram-bot-api:* (Adicionar variável) e reinicie. A versão 2 passa então a registrar cada requisição e cada polling no console.
• Versão do Node.js: a 2.3.0 exige Node.js 18.2 ou mais recente. O Runtime no painel Código oferece Node.js 20, 22 (recommended), 24, 25 e 26.
• Limite de memória: o script de inicialização define NODE_OPTIONS=--max-old-space-size em 80 por cento da memória do seu plano, para que o resto do processo tenha espaço. Detalhes do script de inicialização do Node.js: Como hospedar um bot do Discord em Node.js.

Hospede você mesmo em uma VPS Linux

A versão 2 exige Node.js 18.2 ou mais recente. No Debian 12 ou 13, ou no Ubuntu 24.04, o pacote da distribuição é novo o bastante (o Debian 12 traz Node.js 18.20, o Debian 13 traz 20.19, o Ubuntu 24.04 traz 18.19); o Ubuntu 22.04 traz Node.js 12, que é antigo demais para ela:

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

Crie um usuário para o bot, copie seus arquivos e instale os pacotes:

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

Mantenha o token fora do seu código, em um arquivo que só o root possa ler:

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

Crie /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

Inicie agora e a cada boot, depois acompanhe a saída:

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

Restart=always inicia o bot de novo depois de uma queda ou de um process.exit(1). systemctl stop mybot envia SIGTERM, que run() transforma em uma parada limpa. Pare antes qualquer outra cópia, ou o Telegram responde às duas com 409 Conflict.

Hospedagem própria ou plano de bots

Em uma VPS que você mesmo gerencia, cabe a você cuidar de:

• Atualizações e segurança do sistema operacional, e upgrades do Node.js.
• Rodar npm install após cada mudança, o arquivo de serviço, o arquivo do token e suas permissões.
• Ler o journalctl para descobrir por que o bot parou.
• Backups dos dados do bot.

Em troca, uma VPS roda qualquer coisa, e você pode dar a ela um domínio com HTTPS para um webhook.

Em um plano de bots da PlayNHost, o painel faz isso por você:

• Um seletor de versão do Node.js e npm install quando package.json, o arquivo de lock ou a versão do Node.js mudam.
• O token, verificado com o Telegram antes de ser salvo, guardado criptografado e entregue ao seu código.
• Iniciar o bot de novo depois de uma queda. Se ele cair de novo em um minuto, fica parado e Console diz o motivo.
• Avisos acima de Console que nomeiam a causa quando o Telegram recusa o token, outra cópia está rodando ou há um webhook definido, com um botão Remover webhook no painel Telegram.
• Envio de arquivos, deploys por Git e backups pelo painel.

Perguntas frequentes

Meu bot antigo parou com um erro como TelegramBot is not a constructor. Por quê?

Muito provavelmente o npm instalou a versão 2, que não tem a classe TelegramBot: require('node-telegram-bot-api') agora retorna um objeto com exports nomeados como Bot, e não uma classe que você possa chamar com new. Coloque no package.json a versão para a qual seu bot foi escrito, por exemplo "node-telegram-bot-api": "^0.67.0", apague node_modules e package-lock.json em Files e reinicie: os pacotes são instalados de novo. Ou migre o código para a versão 2 com a tabela do changelog do projeto.

Devo escrever um bot novo na versão 2 ou na 0.x?

Para um bot novo, a versão 2: é a que recebe atualizações, e a 2.3.0 oferece suporte à Bot API 10.3 do Telegram. Mantenha a 0.x para um bot existente até você ter tempo de migrar; ela ainda é instalada pelo npm.

Onde as sessões sobrevivem a uma reinicialização?

Não em MemorySessionStorage: ele vive no processo e fica vazio após cada reinicialização. FileSessionStorage, de node-telegram-bot-api/node, grava um arquivo por chat em uma pasta que você nomeia, por exemplo ./.my_bot_sessions. Nos nossos planos essa pasta fica nos arquivos do seu servidor, então sobrevive às reinicializações e entra nos seus backups.

Pronto para rodar seu bot node-telegram-bot-api o dia todo? Veja os planos em hospedagem de bots do Telegram.