Telegram Bot API

Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless

· 9 min de leitura

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)
RedeSó HTTPS de saída; funciona atrás de NATURL HTTPS pública, portas 443, 80, 88 ou 8443, IPv4
ProcessoLoop de longa duraçãoHandler HTTP; pode ser serverless
InstânciasExatamente uma por tokenVárias atrás de uma URL, sem problema
Bons hostsVPS, Docker, servidor em casaVPS 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:

  1. 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.
  2. Coloque o token em /etc/mybot.env numa linha BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours e restrinja o acesso com chmod 600.
  3. 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

Requisitos de webhook em qualquer host

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

Checklist de deploy

  1. O token vem de uma variável de ambiente ou secret; o getMe funciona no servidor.
  2. Exatamente uma instância de polling por token, ou um webhook com secret_token — nunca os dois.
  3. O processo reinicia sozinho depois de falhas e reboots.
  4. Os logs são coletados e não contêm tokens.
  5. Erros num update são registrados, não derrubam o bot; handlers de webhook devolvem 2XX rápido.
  6. Com webhook, o getWebhookInfo mostra a URL certa e nenhum erro recente.
  7. 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

SintomaCausa e solução
409 Conflict: terminated by other getUpdates requestDuas instâncias fazem polling com o mesmo token (container antigo, seu notebook). Deixe só uma.
409 Conflict mencionando um webhook ativoAinda há um webhook configurado. Chame deleteWebhook antes do polling.
401 UnauthorizedA variável do token está vazia, com erro de digitação ou o token foi revogado. Confira com getMe.
Funciona localmente, mudo no servidorO 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 nadaVeja 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.

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.