TEMPLATE-BOT-TELEGRAM

Esse repositório é um template para facilitar integrações com o Telegram usando o stack padrão do projeto (FastAPI, Celery, Redis, SQLAlchemy).

O objetivo é fornecer um wrapper HTTP minimalista para o Bot API, com suporte a polling (desenvolvimento) e webhook (produção).

Quickstart

1. Copie .env.example para .env e ajuste TELEGRAM_BOT_TOKEN.
2. Instale dependências:

python -m pip install -r requirements.txt

3a. Rodar FastAPI (webhook receiver):

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3b. Rodar polling (desenvolvimento):

python -m app.bot.polling

Estrutura mínima

• app/telegram_client.py — cliente HTTP assíncrono para Bot API
• app/bot/handlers.py — handlers de exemplo (echo)
• app/bot/polling.py — runner simples para getUpdates
• app/main.py — FastAPI com endpoint de webhook

Webhook — Echo verificado

• O handler de exemplo app.bot.handlers.handle_update foi verificado funcionando via webhook: ao enviar uma mensagem para o bot no Telegram, o bot responde com "Echo: ".
• Passos rápidos para testar com webhook:
  1. Atualize TELEGRAM_BOT_TOKEN, TELEGRAM_MODE=webhook e TELEGRAM_WEBHOOK_BASE em .env (ou nas variáveis do container). Não comite TELEGRAM_BOT_TOKEN.
  2. Reinicie a aplicação (ou redeploy via Docker/Coolify). No startup a app tentará registrar o webhook automaticamente e o resultado será escrito nos logs (set_webhook result:).
  3. Envie uma mensagem para o bot no Telegram e verifique que ele responde com Echo: ....

Testar webhook localmente

• Para testes locais, defina TELEGRAM_WEBHOOK_BASE para um URL HTTPS público que encaminhe para sua aplicação (por exemplo, um domínio temporário ou serviço de túnel de sua preferência).
• Reinicie a app (uvicorn ou Docker). Verifique logs para set_webhook result e então envie mensagens ao bot.

Checklist de deploy (Coolify)

• No painel do Coolify, crie um novo serviço apontando para este repositório (Docker Compose).
• Configure as variáveis de ambiente no Coolify (não use .env no repositório):
  • TELEGRAM_MODE=webhook
  • TELEGRAM_WEBHOOK_BASE=https://<seu-domínio>
  • TELEGRAM_BOT_TOKEN (secreto)
• Use docker-compose.prod.yml e docker-compose.prod.override.yml (fornecem configurações limpadas para produção).
• O deploy fará a chamada set_webhook automaticamente no startup quando TELEGRAM_WEBHOOK_BASE estiver presente.

Problemas e troubleshooting

• "TELEGRAM_BOT_TOKEN not set": verifique se a variável está presente no ambiente do container (Coolify UI) ou no .env durante testes locais. -- Webhook não chega: confirme que o TELEGRAM_WEBHOOK_BASE é HTTPS válido (Coolify fornece HTTPS automaticamente).
• Logs úteis:
  • Local (uvicorn): saída do terminal onde uvicorn está rodando.
  • Docker Compose: docker compose logs web --follow.

Containerização e deploy (Coolify)

1. Ajuste o .env:

   • TELEGRAM_MODE=webhook
   • TELEGRAM_WEBHOOK_BASE=https://your-deployed-domain (defina o domínio que o Coolify fornecerá)

2. Build & run localmente com Docker Compose:

docker compose build --no-cache
docker compose up -d

3. Deploy no Coolify:

• Faça push deste repositório para seu Git remoto.
• No painel do Coolify crie um novo serviço usando Docker Compose apontando para este repositório.
• Configure as variáveis de ambiente no painel do Coolify: TELEGRAM_MODE=webhook e TELEGRAM_WEBHOOK_BASE=https://<seu-domínio>.
• Remova o volumes do docker-compose.yml no Coolify (o serviço irá usar a cópia do repositório), e garanta que a command use --app-dir /app/project.

Observações:

• A imagem do web usa /app/project como WORKDIR e o comando padrão do container executa uvicorn app.main:app --app-dir /app/project.
• Após o deploy o serviço fará o set_webhook automaticamente no startup se TELEGRAM_WEBHOOK_BASE estiver configurado.