Como hospedar um bot do Telegram

Para hospedar um bot do Telegram 24/7, rode-o em um servidor que fica sempre ligado, em vez do seu PC: crie o bot no @BotFather, faça o pedido de um plano de bot para o Telegram, cole o token na página Bot e inicie o seu código. Em um plano de bot da PlayNHost (a partir de US$1,99 por mês), o painel confere o token com o Telegram, entrega o token ao seu código com os nomes que a maioria das bibliotecas usa e oferece um bot inicial pronto em Python ou Node.js se você ainda não tem código. Os passos:

1. No Telegram, abra o @BotFather, envie /newbot, escolha um nome e um nome de usuário que termine em bot e copie o token que ele der.
2. Na página Hospedagem de bot do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda Para qual plataforma é o seu bot? com Telegram e escolha a linguagem em que o seu bot foi escrito.
3. Abra o seu servidor no painel. No card Configurar seu bot em Visão geral, confira O que roda e clique em Continuar.
4. Em Conectar ao Telegram, cole o token e clique em Conectar. Confira o nome do bot mostrado e clique em Sim, continuar.
5. Em Seu código, clique em Criar um bot inicial, ou envie os seus próprios arquivos ou conecte o Git.
6. Clique em Iniciar bot e espere por Seu bot está online no Telegram. Envie /start para ele para testar.
7. Na página Bot, seção Telegram, clique em Abrir no Telegram e envie /start ao seu bot.

Cada passo é explicado abaixo.

1. Crie o bot com o @BotFather

1. No Telegram, procure por @BotFather e abra a conversa.
2. Envie /newbot. O @BotFather pede um nome, que as pessoas veem nas conversas, e depois um nome de usuário. O nome de usuário precisa terminar em bot, por exemplo tetris_bot ou TetrisBot.
3. O @BotFather responde com o token, uma linha como 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Copie-o. Quem tem o token controla o seu bot, então não o compartilhe nem o coloque no seu código.

Perdeu o token? No @BotFather, envie /mybots, escolha o seu bot e depois API Token.

2. Faça o pedido de um plano para o Telegram

Todos os planos rodam um bot do Telegram, do STARTER (0,5 GB) em diante. Clique em Criar servidor no plano que você quer. A janela do pedido pergunta Para qual plataforma é o seu bot?: escolha Telegram. Depois você escolhe a linguagem do seu bot: Node.js, Python, Java, C# (.NET), Bun, Deno, Go ou Rust. Não sabe qual plano escolher? python-telegram-bot vs aiogram na PlayNHost traz a memória que medimos para cada biblioteca.

Já tem um plano de bot configurado para o Discord? Você não precisa de outro. Na página Bot, seção Discord, ache o card Para que serve este bot?, escolha Telegram e confirme com Trocar. Nada é apagado: um token do Discord continua salvo e volta se você trocar de novo. Se você já tinha salvo o seu token em Ambiente como TELEGRAM_BOT_TOKEN, ele vira o token do Telegram, sem nada para colar de novo.

3. Cole o token

Abra o seu servidor no painel. O card Configurar seu bot em Visão geral leva você por três etapas: O que roda, Conectar ao Telegram e Seu código.

1. O que roda mostra a linguagem do seu servidor, por exemplo Este bot roda Python Bot. Clique em Continuar, ou em Mudar o que roda se não for a certa.
2. Conectar ao Telegram: cole o token em Cole o token do seu bot e clique em Conectar. O painel mostra Verificando com o Telegram... e depois o nome e o @usuário do seu bot com Este é o seu bot?. Clique em Sim, continuar.

Você também pode colá-lo na página Bot, seção Telegram, em Token. Um token que o Telegram recusa não é salvo: você vê O Telegram não aceitou esse token. Copie-o de novo do @BotFather.

O token fica guardado criptografado e nunca é mostrado de novo no painel. Seu código o recebe como variável de ambiente com cinco nomes, então a maioria dos exemplos roda sem mudanças:

Em Python, leia-o com os.environ["TELEGRAM_BOT_TOKEN"]; em Node.js, com process.env.TELEGRAM_BOT_TOKEN.

4. Adicione o seu código

Em Seu código, o card oferece o que combina com o seu servidor:

• Criar um bot inicial (servidores Node.js e Python ainda sem código): um bot pequeno que já funciona e responde ao /start. Em Python, ele grava bot.py e requirements.txt com python-telegram-bot 22; em Node.js, grava index.js e package.json com grammY. Ele já define o arquivo de entrada para você. Mude como quiser e depois reinicie.
• Enviar arquivos: o seu próprio bot, com requirements.txt ou package.json. Deixe de fora venv, .venv, __pycache__ e node_modules. Veja Como enviar o código do seu bot.
• Conectar o Git: o seu código de um repositório Git. Veja Como fazer deploy e atualizar seu bot pelo GitHub.

O seu código precisa usar long polling: run_polling() no python-telegram-bot, start_polling() no aiogram, bot.start() no grammY ou launch() no Telegraf. Webhooks precisam de um endereço HTTPS público, que esses planos ainda não incluem. Para mover um bot que usava webhook: Como migrar um bot do Telegram para a PlayNHost.

5. Inicie o bot

Clique em Iniciar bot no card, ou em Iniciar, e abra o Console. Em Python, Node.js e Bun, o servidor instala os seus pacotes primeiro; a primeira inicialização demora mais enquanto eles são baixados. Depois disso, eles só são instalados de novo quando você os muda (a lista de pacotes, o arquivo de pacotes ou a versão do runtime), quando falta o node_modules ou uma vez por dia. Fora isso, você vê:

[PlayNHost] Packages are up to date. They install again when you change them, or after a day.
[PlayNHost] Starting your bot

O bot inicial então imprime Logged in as @your_bot. O painel lê essa linha: o chip em Visão geral passa para Online no Telegram. No seu próprio código, imprima uma linha parecida quando o bot estiver pronto.

6. Abra o bot no Telegram

Na página Bot, seção Telegram, clique em Abrir no Telegram. Ele abre o link t.me do seu bot. Envie /start: o bot inicial responde Hello com o seu primeiro nome e Your bot is running on PlayNHost.

A mesma seção mostra o @usuário e o id do seu bot, e um card Em grupos com o que o Telegram permite que ele faça em chats de grupo.

Se ele não responder

O painel lê o console e coloca um aviso acima dele com a causa e um botão para corrigir:

• O Telegram não aceitou o token do seu bot: o token foi revogado no @BotFather ou copiado errado. Clique em Substituir o token.
• Seu bot também está rodando em outro lugar: outra cópia usa o mesmo token, muitas vezes no seu PC ou na sua hospedagem antiga.
• Há um webhook configurado no seu bot: clique em Remover o webhook.

Algumas bibliotecas continuam tentando nesses casos, então o bot parece estar rodando enquanto nada responde: o aviso é como você descobre. Detalhes: Como corrigir o erro 409 Conflict do bot do Telegram.

Perguntas frequentes

Meu bot fica online quando eu desligo o PC?

Sim. Ele roda no servidor, não no seu PC nem no seu navegador. Se ele travar, é iniciado de novo em cerca de um minuto; se travar outra vez dentro de um minuto depois disso, ele fica parado e o Console diz o motivo.

Posso usar webhook em vez de polling?

Ainda não. Um webhook precisa de um endereço HTTPS público, que esses planos ainda não incluem. O polling não precisa de endereço: o seu bot pede ao Telegram as mensagens novas. Se houver um webhook configurado no seu bot, a seção Telegram o mostra com Remover webhook, que mantém as mensagens em espera.

Posso rodar o mesmo bot no meu PC enquanto testo?

Não com o mesmo token ao mesmo tempo. O Telegram deixa só uma cópia de um bot pedir mensagens, então a outra recebe 409 Conflict. Pare a cópia no seu PC ou crie um segundo bot no @BotFather para testar.

Por que o meu bot não vê as mensagens em um grupo?

O modo de privacidade do Telegram vem ligado por padrão: em grupos, o seu bot vê os comandos destinados a ele e as respostas a ele, não todas as mensagens, a menos que seja administrador do grupo. O card Em grupos mostra Privacidade ativada ou Privacidade desativada. Para ler todas as mensagens, envie /setprivacy ao @BotFather, desative o modo, depois remova o bot do grupo e adicione-o de novo.

De qual plano eu preciso?

O STARTER (0,5 GB) roda um bot python-telegram-bot, aiogram, grammY ou Telegraf com espaço para o seu código. Escolha 1 GB ou mais quando o bot guardar dados na memória, lidar com arquivos ou imagens, ou rodar vários bots em um só processo. Veja os planos em Hospedagem de bot do Telegram.