Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless
Para hospedar um bot do Telegram, rode o código numa máquina sempre ligada que alcance api.telegram.org e escolha como ele recebe os updates: long polling com getUpdates, que funciona em qualquer servidor sem domínio, ou webhook, que exige uma URL HTTPS pública. Uma VPS pequena com systemd ou um container Docker é a escolha comum para bots com polling; plataformas serverless como o Cloudflare Workers combinam com bots via webhook. Este guia mostra cada opção com configurações prontas para copiar, além de logs, reinícios e um checklist de deploy.
Polling ou webhook no servidor
O Telegram oferece duas formas mutuamente exclusivas de receber updates, e em ambas os updates não entregues ficam guardados por no máximo 24 horas. A escolha define o que a hospedagem do bot precisa ter:
Long polling (getUpdates) | Webhook (setWebhook) | |
|---|---|---|
| Rede | Só HTTPS de saída; funciona atrás de NAT | URL HTTPS pública, portas 443, 80, 88 ou 8443, IPv4 |
| Processo | Loop de longa duração | Handler HTTP; pode ser serverless |
| Instâncias | Exatamente uma por token | Várias atrás de uma URL, sem problema |
| Bons hosts | VPS, Docker, servidor em casa | VPS com proxy reverso, Cloudflare Workers, AWS Lambda, Vercel |
Se o polling já funciona na sua máquina, mantenha: o próprio guia de webhooks do Telegram diz que não há nada de errado em usar getUpdates. Mude para webhook quando a plataforma exigir ou quando quiser dividir a carga entre várias instâncias.
Um bot com polling pronto para deploy
Código pronto para produção tem três características: lê o token de uma variável de ambiente, escreve logs no stdout e sobrevive a erros de rede em vez de cair. Este bot de eco faz as três coisas e chama deleteWebhook na inicialização, porque o getUpdates não funciona com webhook ativo:
import logging
import os
import time
import requests
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")
TOKEN = os.environ["BOT_TOKEN"] # nunca coloque o token direto no código
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def main():
call("deleteWebhook") # polling e webhook são mutuamente exclusivos
log.info("iniciado como @%s", call("getMe")["username"])
offset = 0
while True:
try:
updates = call("getUpdates", offset=offset, timeout=30)
except Exception:
log.exception("getUpdates falhou, nova tentativa em 5 s")
time.sleep(5)
continue
for update in updates:
offset = update["update_id"] + 1
msg = update.get("message")
if msg and "text" in msg:
try:
call("sendMessage", chat_id=msg["chat"]["id"], text="Eco: " + msg["text"])
except Exception:
log.exception("update %s falhou", update["update_id"])
if __name__ == "__main__":
main()const TOKEN = process.env.BOT_TOKEN; // nunca coloque o token direto no código
if (!TOKEN) throw new Error("BOT_TOKEN não está definido");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
await call("deleteWebhook"); // polling e webhook são mutuamente exclusivos
log("iniciado como @" + (await call("getMe")).username);
let offset = 0;
while (true) {
let updates;
try {
updates = await call("getUpdates", { offset, timeout: 30 });
} catch (err) {
log("getUpdates falhou, nova tentativa em 5 s:", err.message);
await sleep(5000);
continue;
}
for (const update of updates) {
offset = update.update_id + 1;
const msg = update.message;
if (!msg?.text) continue;
try {
await call("sendMessage", { chat_id: msg.chat.id, text: "Eco: " + msg.text });
} catch (err) {
log(`update ${update.update_id} falhou:`, err.message);
}
}
}Salve como bot.py (com requests no requirements.txt) ou bot.mjs (Node.js 18+, sem dependências). Os frameworks da lista de bibliotecas cuidam do loop para você, mas os passos de deploy abaixo continuam os mesmos.
Bot do Telegram numa VPS com systemd
A VPS é uma máquina Linux comum. Deixe o systemd iniciar o bot no boot e reiniciá-lo quando cair:
- Crie um usuário sem permissão de login e copie o código para
/opt/mybot; em Python, crie ali um ambiente virtual e instale as dependências. - Coloque o token em
/etc/mybot.envnuma linhaBOT_TOKEN=123456789:AAEexampleTokenReplaceWithYourse restrinja o acesso comchmod 600. - Crie o arquivo de unidade
/etc/systemd/system/mybot.service:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target
[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
Ative o serviço e acompanhe os logs:
sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f # logs em tempo real
sudo systemctl restart mybot # depois de atualizar o código
Para webhook na mesma VPS, rode o bot como servidor HTTP numa porta local e coloque nginx ou Caddy na frente para terminar o TLS na porta 443; o guia de webhook traz um handler com a verificação do secret token.
Deploy do bot do Telegram com Docker
O container empacota o runtime e as dependências, então o bot roda igual no seu notebook e em qualquer host com Docker. Um Dockerfile para o bot em Python:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]
Faça o build e rode passando o token em tempo de execução, nunca embutido na imagem:
docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot
O --restart unless-stopped traz o bot de volta depois de falhas e reboots do host. Deixe o .env fora do Git e da imagem (inclua no .dockerignore). Ao refazer o deploy de um bot com polling, pare o container antigo antes de subir o novo: dois containers fazendo polling com o mesmo token fazem o getUpdates falhar com 409 Conflict.
Serverless: bot do Telegram no Cloudflare Workers
Plataformas serverless só executam código quando chega uma requisição, então exigem o modo webhook. No Cloudflare Workers o endereço padrão workers.dev já serve HTTPS na porta 443. Este Worker confere o header do secret token, responde na hora e termina o trabalho em segundo plano com ctx.waitUntil:
// worker.js: deploy com "npx wrangler deploy"
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
return new Response("Not found", { status: 404 });
}
const enc = new TextEncoder();
const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
const expected = enc.encode(env.WEBHOOK_SECRET);
if (received.byteLength !== expected.byteLength ||
!crypto.subtle.timingSafeEqual(received, expected)) {
return new Response("Forbidden", { status: 403 });
}
const update = await request.json();
ctx.waitUntil(handleUpdate(update, env)); // responde 200 agora e continua trabalhando
return new Response("OK");
},
};
async function handleUpdate(update, env) {
const msg = update.message;
if (!msg?.text) return;
const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: msg.chat.id, text: "Eco: " + msg.text }),
});
if (!res.ok) console.error("sendMessage falhou", res.status, await res.text());
}
Guarde os dois valores como secrets do Worker, faça o deploy e registre a URL do Worker com o mesmo segredo:
npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
-H "Content-Type: application/json" \
-d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "troque-pelo-seu-segredo-aleatorio"}'
Ou preencha o setWebhook no Bot API Tester. O mesmo padrão funciona no AWS Lambda (atrás de uma function URL HTTPS ou de um API gateway) e nas functions da Vercel: leia o corpo JSON, confira o header e devolva 2XX rápido. As plataformas limitam quanto tempo a função e o trabalho em segundo plano podem rodar, então mande tarefas lentas para uma fila. O Telegram repete toda resposta que não seja 2XX, então uma função que estoura o tempo ou cai recebe o mesmo update de novo.
Formas gratuitas e baratas de hospedar um bot do Telegram
- Planos gratuitos serverless servem para bots com webhook, tráfego moderado e handlers curtos.
- Uma VPS pequena é a opção mais flexível: polling ou webhook, qualquer linguagem, banco de dados ao lado do bot.
- Um servidor em casa ou um computador de placa única funciona com polling, já que não precisa de conexão de entrada; a disponibilidade depende da sua energia e internet.
- Plataformas de containers que mantêm o processo rodando podem hospedar um bot com polling; confira se não colocam apps ociosos para dormir.
Requisitos de webhook em qualquer host
- Só HTTPS, TLS 1.2 ou superior, certificado que bata com o domínio e cadeia completa, ou certificado autoassinado enviado via
certificate. - Portas 443, 80, 88 ou 8443; IPv4 (IPv6 não é suportado para webhooks); sem redirecionamentos.
- As requisições vêm de
149.154.160.0/20e91.108.4.0/22; o Telegram avisa que essas faixas podem mudar. - Defina o
secret_token(1–256 caracteresA-Z a-z 0-9 _ -) e confira o headerX-Telegram-Bot-Api-Secret-Token.
Depois de cada deploy, abra o getWebhookInfo no Bot API Tester: um pending_update_count que só cresce ou um last_error_message recente significa que o Telegram não consegue entregar os updates.
Variáveis de ambiente, logs e reinícios
- Token: só em variável de ambiente ou cofre de segredos, nunca no Git, em imagens ou em código cliente. Se vazar, revogue como explicado no guia do token do bot e atualize o servidor.
- Logs: escreva no stdout/stderr e deixe o journald, o Docker ou a plataforma coletarem. Não registre URLs completas das requisições, porque elas contêm o token.
- Reinícios: um supervisor (
Restart=always,--restart unless-stopped) cuida das falhas. O Telegram guarda do lado dele quais updates foram confirmados: um update é confirmado quando ogetUpdatesé chamado com umoffsetmaior, então após um reinício o bot recebe só os não confirmados. O último lote antes de uma falha pode chegar duas vezes; descarte duplicados peloupdate_idonde isso importar. - Limites de taxa: trate o
429 Too Many Requestsesperandoretry_aftersegundos; veja os limites da Telegram Bot API.
Checklist de deploy
- O token vem de uma variável de ambiente ou secret; o
getMefunciona no servidor. - Exatamente uma instância de polling por token, ou um webhook com
secret_token— nunca os dois. - O processo reinicia sozinho depois de falhas e reboots.
- Os logs são coletados e não contêm tokens.
- Erros num update são registrados, não derrubam o bot; handlers de webhook devolvem 2XX rápido.
- Com webhook, o
getWebhookInfomostra a URL certa e nenhum erro recente. - Para experimentos, use um bot de teste separado ou o servidor de testes do Telegram, não o token de produção.
Problemas comuns no deploy
| Sintoma | Causa e solução |
|---|---|
409 Conflict: terminated by other getUpdates request | Duas instâncias fazem polling com o mesmo token (container antigo, seu notebook). Deixe só uma. |
409 Conflict mencionando um webhook ativo | Ainda há um webhook configurado. Chame deleteWebhook antes do polling. |
401 Unauthorized | A variável do token está vazia, com erro de digitação ou o token foi revogado. Confira com getMe. |
| Funciona localmente, mudo no servidor | O HTTPS de saída para api.telegram.org está bloqueado ou o arquivo de ambiente não foi carregado. Veja os logs. |
| Bot com webhook não recebe nada | Veja o last_error_message no getWebhookInfo: TLS, porta errada, 403 por segredo divergente ou handler que cai. |
Começando agora com bots? Veja primeiro como criar um bot no Telegram e depois volte para fazer o deploy.
Perguntas frequentes
Onde posso hospedar um bot do Telegram?
Em qualquer lugar que faça requisições HTTPS de saída: uma VPS, um host com Docker, um servidor em casa ou uma plataforma serverless. Bot com getUpdates não precisa de endereço público; bot com webhook precisa de uma URL HTTPS pública na porta 443, 80, 88 ou 8443.
Em produção, o bot deve usar polling ou webhook?
Os dois funcionam em produção. Long polling com getUpdates é o mais simples numa VPS ou no Docker, porque dispensa domínio e certificado. Webhook é obrigatório em plataformas serverless, que só executam código quando chega uma requisição.
Por que recebo 409 Conflict depois do deploy do bot?
Ou ainda há um webhook configurado enquanto o bot faz polling com getUpdates (chame deleteWebhook), ou duas cópias do bot estão fazendo polling ao mesmo tempo — por exemplo, o container antigo e o novo durante o deploy, ou o seu notebook e o servidor. Rode exatamente uma instância de polling por token.
Como manter um bot do Telegram rodando 24/7?
Rode-o sob um supervisor de processos que reinicie depois de falhas e reboots: um serviço systemd com Restart=always na VPS ou um container Docker com --restart unless-stopped. Escreva os logs no stdout e acompanhe com journalctl ou docker logs.
Dá para rodar um bot do Telegram no Cloudflare Workers?
Sim, no modo webhook. O Worker recebe cada update como uma requisição POST, confere o header X-Telegram-Bot-Api-Secret-Token e chama a Bot API com fetch. Registre o endereço HTTPS workers.dev com setWebhook. Um loop de long polling não se encaixa nesse modelo.
Onde guardar o token do bot no servidor?
Numa variável de ambiente carregada de um arquivo que só o usuário do bot consegue ler, ou no cofre de segredos da plataforma (por exemplo, um secret do Worker). Nunca faça commit do token no Git nem o embuta na imagem Docker. Se vazar, revogue no @BotFather.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais
Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.
Erros do Telegram Bot API: o que cada erro significa e como resolver
Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.
Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens
Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.
Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start
Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.
Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard
Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.
Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens
Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Bot inline no Telegram: como ativar o modo inline e responder às consultas
Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.
Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas
Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.
Como testar uma Mini App do Telegram: do mock no navegador ao app real
Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.