Como hospedar um bot do Telegram 24/7

Um bot do Telegram é um programa que recebe atualizações (mensagens, comandos, cliques em botões) e responde pela Bot API. Diferente de um bot do Discord, ele não mantém um WebSocket aberto: o Telegram entrega as atualizações por HTTP. Mesmo assim, um processo seu precisa ficar no ar para buscá-las ou recebê-las, e é aí que entra a hospedagem.

A seguir você cria o token, escolhe o modo de recebimento, roda o código e confere que deu certo. Os exemplos usam Python com a API do python-telegram-bot 22; confira no PyPI a versão atual da biblioteca e a versão mínima do Python que ela exige.

O que significa manter um bot do Telegram 24/7?#

Significa ter um processo rodando sem parar numa máquina que não desliga, e que volta sozinho se travar. O código do bot é só um laço que busca ou recebe atualizações e chama as suas funções. Se o processo morre, ninguém responde.

Rodar no seu computador funciona para testar, mas o bot cai quando a máquina dorme, reinicia ou perde a conexão. Para um bot que outras pessoas usam, o normal é um servidor sempre ligado: um VPS, um container ou uma plataforma de hospedagem. Veja o que esperar das opções sem custo em limites da hospedagem sem custo.

Como criar o bot e pegar o token?#

1. Abra uma conversa com o @BotFather no Telegram.
2. Envie /newbot e siga as perguntas (nome e username, que termina em bot).
3. Copie o token que ele devolve. Tem o formato de um número, dois-pontos e uma sequência de caracteres.

O token autentica o bot, não a sua conta, e vale como senha: quem o tem controla o bot. A documentação do Telegram recomenda não deixá-lo no código e guardá-lo em variáveis de ambiente ou num arquivo de configuração. Se vazar, revogue pelo BotFather. Entenda o conceito em o que são variáveis de ambiente.

Long polling ou webhook?#

O Telegram oferece dois jeitos de entregar atualizações, e você só pode usar um por vez:

No long polling, o getUpdates aceita um timeout em segundos: com valor maior que zero, a conexão fica aberta esperando novidades em vez de consultar o tempo todo. O padrão é 0, que é polling curto. As bibliotecas já configuram isso por você.

No webhook, a URL precisa ser HTTPS. Você pode definir um secret_token de 1 a 256 caracteres (letras, números, _ e -), que o Telegram devolve no cabeçalho X-Telegram-Bot-Api-Secret-Token para você descartar requisições falsas. O padrão é até 40 conexões simultâneas (max_connections).

Para a maioria dos bots, comece pelo polling. Migre para webhook se precisar de volume ou já tiver um servidor HTTPS.

Como rodar um bot com long polling?#

Instale a biblioteca e crie um arquivo bot.py:

pip install "python-telegram-bot>=22,<23"

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Estou online!")


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

Defina BOT_TOKEN no ambiente e rode python bot.py. O run_polling bloqueia o processo e trata sinais de encerramento. Mande /start ao bot: se ele responder, o ciclo está funcionando.

Em outras bibliotecas a ideia é a mesma: aiogram (Python), Telegraf e grammY (Node.js) têm um método de inicialização que entra em polling.

Como rodar com webhook?#

Troque run_polling por run_webhook. Instale o extra de webhooks:

pip install "python-telegram-bot[webhooks]>=22,<23"

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Estou online via webhook!")


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.run_webhook(
        listen="0.0.0.0",
        port=int(os.environ.get("PORT", "8080")),
        url_path="telegram",
        webhook_url=f"{os.environ['PUBLIC_URL']}/telegram",
        secret_token=os.environ["WEBHOOK_SECRET"],
    )


if __name__ == "__main__":
    main()

PUBLIC_URL é o endereço HTTPS público do seu servidor (por exemplo https://meubot.exemplo.com). PORT e PUBLIC_URL são só nomes de exemplo. A porta de webhook_url deve ser uma das aceitas pelo Telegram (443, 80, 88 ou 8443); se um proxy reverso recebe o tráfego, o bot pode escutar em outra porta local. A biblioteca chama setWebhook na inicialização e valida o secret_token em cada requisição. Para entender o certificado desse endereço, veja como funciona o Let's Encrypt.

Como manter o processo vivo?#

Hospedar 24/7 é, na prática, três garantias:

• Reinício automático: em um VPS, use systemd ou um supervisor de processos como o pm2; em plataformas, confira se o reinício já vem incluído.
• Variáveis fora do código: token e segredo do webhook entram por ambiente, nunca no repositório.
• Logs: sem logs você não sabe por que o bot parou. Imprima erros e leia a saída do processo.

O Telegram guarda atualizações pendentes por até 24 horas. Numa queda curta você não perde mensagens; numa de mais de um dia, perde.

Como saber se o bot está online?#

• Envie um comando e veja se ele responde.
• Chame o método getMe da Bot API para validar o token (nunca compartilhe a URL com o token).
• No webhook, getWebhookInfo mostra a URL cadastrada, o número de atualizações pendentes e o último erro de entrega.

Quais são os erros comuns?#

• O bot não responde em modo webhook: a URL não é HTTPS válido, a porta não é uma das permitidas ou o secret_token não confere. Veja last_error_message no getWebhookInfo.
• Conflict: terminated by other getUpdates request: duas instâncias do mesmo bot em polling. Pare a outra, inclusive a do seu PC.
• getUpdates não funciona: há um webhook ativo. Remova com deleteWebhook.
• Unauthorized (no python-telegram-bot, InvalidToken): token errado ou revogado. Confira a variável de ambiente.
• Bot cai depois de algumas horas: o processo foi encerrado por falta de memória ou por um erro não tratado. Veja os logs.

Como fazer isso na Square Cloud#

Na Square Cloud, os dois modos deste artigo funcionam sem mudar o código. Em long polling, o bot é uma aplicação de fundo: ele só faz requisições de saída, não precisa de subdomínio e usa a partir de 256 MB de RAM. Para webhook, crie uma aplicação web com subdomínio: ela ganha um endereço squareweb.app com HTTPS, que vai em PUBLIC_URL, e o exemplo acima já escuta em 0.0.0.0 na porta da variável PORT, que a plataforma define. A URL pública usa HTTPS na porta padrão, que o Telegram aceita, e uma aplicação web usa a partir de 512 MB.

As três garantias para manter o processo vivo já vêm com o container. Ele fica sempre ligado, sem modo de suspensão, e o reinício automático, ligado por padrão no deploy pelo painel, sobe o bot quando o processo encerra com erro. Se a memória estourar, a aplicação para e só volta quando você aumenta a RAM e a inicia de novo. BOT_TOKEN e WEBHOOK_SECRET entram como variáveis de ambiente da aplicação, e os logs em tempo real mostram por que o bot caiu. Ao fazer o deploy, pare a cópia que roda no seu PC, ou o polling volta a dar Conflict.

O bot funciona com python-telegram-bot, aiogram, Telethon, Telegraf ou grammY. O Hobby custa R$ 12,49 por mês com 1 GB de RAM compartilhado entre as suas aplicações. Veja os detalhes em hospedagem de bots do Telegram.