Ping-Tower / Telegram Bot

Part of the Ping-Tower uptime monitoring system. 📖 Full project description and architecture →

Telegram notification channel. Serves the /start bot flow (webhook or polling) and delivers server up/down alerts pushed from the API through RabbitMQ.

Stack

Python / FastAPI, aiogram (Telegram Bot API), faststream[rabbit] (RabbitMQ consumer), pydantic-settings, uv

Role in the system

telegramQueue ──▶ [ Telegram Bot ] ──Bot API──▶ Telegram user

• Consumes notification messages from telegramQueue via faststream and delivers them through aiogram, with inline keyboards (Web app / GitHub buttons on /start).
• Runs in either webhook mode (FastAPI endpoint at TG_BOT_WEBHOOK_PATH, verified with TG_BOT_WEBHOOK_SECRET) or polling mode, selected via TG_BOT_MODE.
• Account linking: users connect their Telegram account to a PingTower user via the API's telegram-accounts endpoints.

Running locally

cp .env.example .env
# fill in TG_BOT_BOT_TOKEN

uv sync
uv run tg-bot

Or via Docker:

cp .env.example .env
docker compose up --build

Key environment variables (.env.example): TG_BOT_BOT_TOKEN, TG_BOT_MODE (polling/webhook), TG_BOT_WEBHOOK_*, TG_BOT_RABBITMQ_URL, TG_BOT_RABBITMQ_QUEUE, TG_BOT_PROXY_URL (optional outbound proxy for the Bot API).

Tests

uv run pytest tests/unit
uv run pytest tests/integration

CI/CD (GitLab)

.gitlab-ci.yml: test (pytest) → build (Docker image, push, main/stage only) → deploy (SSH, docker compose pull && up -d).