Como hospedar um bot Telegraf 24/7 (Telegram, Node.js)

Para hospedar um bot Telegraf 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 para 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 reinicia o bot se ele cair. No nosso teste, um bot com Telegraf 4.16.3 usou cerca de 60 MB de memória no Node.js 22. O bot.launch() do Telegraf usa long polling por padrão, que é o que nossos planos precisam: eles ainda não têm um endereço HTTPS público para um webhook. Os passos na PlayNHost:

1. Em hospedagem de bots do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda 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. Em Seu código, clique em Enviar arquivos e envie seu package.json e seu index.js sem node_modules, ou clique em Conectar o Git.
5. Na página Bot, painel Código, confirme que Arquivo de entrada é o arquivo que inicia seu bot (index.js por padrão). Clique em Salvar se você mudar.
6. Clique em Iniciar bot e abra Console. O npm instala o Telegraf 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.
7. Na página Bot, painel Telegram, clique em Abrir no Telegram e envie /start ao seu bot.

Como criar o bot no @BotFather e os passos do painel são explicados em Como hospedar um bot do Telegram. Esta página trata do Telegraf em si: o que ele usa em um servidor e o que saber antes de hospedá-lo.

O que medimos

Como: no nosso próprio nó, em um contêiner descartável configurado como um plano de bot 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 inicialização vai do launch até a resposta e cada valor é a mediana das execuções 2 a 4.

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

Um bot Telegraf mínimo

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-telegraf-bot",
  "private": true,
  "main": "index.js",
  "dependencies": {
    "telegraf": "^4.16.3"
  }
}

index.js

const { Telegraf } = require("telegraf");

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

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

// Without this, an error in one command stops the whole bot.
bot.catch((err, ctx) => {
  console.error(`Error while handling update ${ctx.update.update_id}:`, err);
});

// launch() only returns when the bot stops, so the ready line goes in its callback.
bot.launch(() => console.log(`Logged in as @${bot.botInfo.username}`)).catch((err) => {
  if (err.code === 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.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

Os exemplos do próprio Telegraf 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 funcionam sem alterações. A linha Logged in as @your_bot é o que muda o indicador para Online no Telegram.

Se o token estiver errado

No nosso teste, com um token falso, o bot.launch() do Telegraf falhou com um TelegramError cujo err.code é 401. Impresso como nome e mensagem, aparece assim:

Error: 401: Unauthorized

O nome aparece como Error porque a classe de erro do Telegraf não define um nome próprio. O Telegraf não tenta de novo um token recusado: o bot.launch() falha na hora, e o mesmo vale para um bot que não recebeu token algum (401: Bot Token is required). O bot acima captura os dois casos e imprime em vez disso 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.

O que saber sobre o Telegraf em um servidor

• Versões: o Telegraf mais recente é o 4.16.3, lançado em 29 fev 2024. A versão 4.16.0 (25 fev 2024) adicionou as Bot API 7.0 e 7.1 do Telegram; o changelog do próprio Telegram está na Bot API 10.3 (24 ago 2026). O repositório do GitHub recebeu o último push em 24 set 2026. No nosso teste, a 4.16.3 foi instalada e iniciada normalmente no Node.js 22.
• A linha de pronto vai no callback do launch(). O bot.launch() só retorna quando o bot para, então um console.log depois de await bot.launch() nunca é impresso enquanto ele roda. Desde a 4.16.0, o launch() aceita um callback que o Telegraf chama quando o Telegram aceita o token, com bot.botInfo preenchido.
• Um erro em um comando para o bot se você não definir bot.catch. O handler padrão do Telegraf imprime Unhandled error while processing com a atualização e lança o erro de novo, o que encerra o polling, e o processo para. Nosso painel reinicia um bot que caiu em cerca de um minuto, mas até lá ele fica offline. Com bot.catch, como acima, o erro é impresso e o bot continua.
• Cada atualização tem 90 segundos. Uma atualização cujos handlers demoram mais é reportada como erro (a opção handlerTimeout, 90.000 ms por padrão), que então vai para bot.catch. Passe new Telegraf(token, { handlerTimeout: ... }) para tarefas mais longas.
• Um webhook deixado no bot é removido para você. O bot.launch() sem a opção webhook chama deleteWebhook antes de fazer polling e mantém as mensagens em espera, a menos que você passe dropPendingUpdates: true. O bot.launch({ webhook: ... }) precisa de um endereço HTTPS público, que esses planos ainda não incluem: use o bot.launch() simples. Se você está saindo de um host com webhook: Como migrar um bot do Telegram para a PlayNHost.
• Outra cópia do bot para esta. Com 409 Conflict (o mesmo token fazendo polling em outro lugar), o polling do Telegraf lança um erro em vez de tentar de novo. O painel mostra Seu bot também está rodando em outro lugar: pare a cópia no seu PC ou no seu host antigo. Veja Como corrigir o erro 409 Conflict do bot do Telegram. Durante o polling, erros de rede, 429 e os erros 5xx do próprio Telegram são repetidos após a espera que o Telegram pede, ou 5 segundos.
• Versão do Node.js: o Telegraf 4.16.3 exige Node.js 12.20 ou 14.13.1 e superiores. 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

No Debian 12 ou 13, ou no Ubuntu 24.04, o pacote da distribuição basta para o Telegraf (o Debian 12 traz Node.js 18.20, o Debian 13 traz 20.19, o Ubuntu 24.04 traz 18.19):

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 pode ler:

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

Crie o /etc/systemd/system/mybot.service:

[Unit]
Description=Telegraf 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-o 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). O systemctl stop mybot envia SIGTERM, que as linhas process.once transformam em bot.stop(). Pare qualquer outra cópia antes, ou o Telegram responde às duas com 409 Conflict.

Hospedar você mesmo ou um plano para bots

Em uma VPS que você mesmo gerencia, você cuida de:

• Atualizações e segurança do sistema operacional, e upgrades do Node.js.
• Executar 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 para 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, armazenado criptografado e entregue ao seu código.
• Reiniciar o bot depois de uma queda. Se ele cair de novo em menos de um minuto, fica parado e Console diz o motivo.
• Avisos acima de Console que indicam 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.
• Upload, deploys pelo Git e backups pelo painel.

Perguntas frequentes

Por que nada é impresso depois de await bot.launch()?

Porque o bot.launch() espera o polling terminar, e o polling dura enquanto o bot roda. O código depois dele só executa quando o bot para. Coloque as mensagens de inicialização no callback, bot.launch(() => ...), e registre os comandos antes de chamar launch().

Posso continuar usando o Telegraf ou devo migrar para o grammY?

Um bot Telegraf 4 que funciona roda nos nossos planos do jeito que está: não há nada para mudar para hospedá-lo. A última versão é de fevereiro de 2024, então os métodos que o Telegram adicionou depois da Bot API 7.1 não têm atalho no Telegraf. O grammY 1.46.0 (26 ago 2026) oferece suporte à Bot API 10.3, e nosso bot inicial para Node.js o usa. Migre quando precisar de algo mais novo do que o Telegraf oferece.

Meu bot Telegraf parou com 409: Conflict. E agora?

Outra cópia está fazendo polling com o mesmo token, muitas vezes no seu PC ou no seu host antigo. O Telegraf para em vez de tentar de novo. O painel o reinicia em cerca de um minuto; se ele parar de novo dentro de um minuto depois disso, fica parado. Encontre e pare a outra cópia, ou crie um token novo no @BotFather e cole-o com Substituir token.

Posso rodar o Telegraf no Bun?

Sim. Ao fazer o pedido, escolha Bun em vez de Node.js: nossa página de hospedagem de bots do Telegram lista o Telegraf para ele. Os passos desta página são para Node.js.

Pronto para rodar seu bot Telegraf o dia todo? Veja os planos em hospedagem de bots do Telegram.