Telegram Message Hook

A container-friendly FastAPI service that sends predefined Telegram messages when specific webhook URLs are triggered. It offers a modern single-page interface for managing hook entries and handles user authentication with Telegram (via Telethon) directly in the browser.

✨ Features

• User session login through the web UI using Telethon (no CLI prompts).
• Create, list, trigger, edit IDs, and delete hook entries that map to Telegram chat IDs and Markdown-enabled messages.
• Each hook automatically receives a short unique identifier and an action URL.
• Persistent storage backed by a prettified JSON file (stored in /data/hooks.json inside the container).
• Docker image and Traefik-ready docker-compose.yml (uses an external proxy network and dummy host values).
• Environment-driven configuration for all sensitive credentials.

⚙️ Configuration

Variable	Required	Description
TELEGRAM_API_ID	✅	Telegram API ID (from https://my.telegram.org).
TELEGRAM_API_HASH	✅	Telegram API hash.
TELEGRAM_PHONE	➖	Default phone number to prefill in the login form.
TELEGRAM_SESSION_NAME	➖	Logical name for the session file (default telegram).
TELEGRAM_SESSION_PATH	➖	Absolute path to the Telethon session file (default data/telegram.session).
DATABASE_PATH	➖	Absolute path to the hooks JSON file (default data/hooks.json).
BASE_URL	➖	Public base URL used to render action links (default http://localhost:8000).
HOOK_ID_LENGTH	➖	Length of generated hook IDs (default 8).

Create an .env file (optional) to keep these together locally; the application loads it automatically.

🚀 Local Development

Windows quick start

You can bootstrap everything with the PowerShell helper:

scripts\run_local.ps1

The script ensures the data folder exists, sets default paths for the hooks JSON file and Telethon session, and then launches Uvicorn with hot reload. Provide real Telegram credentials via environment variables or an .env file before running it.

Manual setup

1. Install dependencies:

pip install -r requirements-dev.txt

2. Export your credentials (or create an .env). For PowerShell:

$env:TELEGRAM_API_ID = "123456"
$env:TELEGRAM_API_HASH = "your_api_hash"
# Optional tweaks
$env:BASE_URL = "http://localhost:8000"

3. Launch the API server:

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

4. Open http://localhost:8000 to log in and manage hooks.

🧪 Test Suite

Run the unit tests (Telethon interactions are safely stubbed):

python -m pytest

🐳 Docker

Build the image:

docker build -t telegram-hook .

Run with environment variables and a bind-mounted data folder:

docker run --rm -p 8000:8000 `
  -e TELEGRAM_API_ID=123456 `
  -e TELEGRAM_API_HASH=your_api_hash `
  -e TELEGRAM_PHONE=+491234567890 `
  -e BASE_URL=https://hook.example.com `
  -v ${PWD}\data:/data `
  telegram-hook

Docker Compose + Traefik

docker-compose.yml is pre-configured with Traefik labels and an external network called proxy:

services:
  telegram-hook:
    labels:
      traefik.http.routers.telegramhook.rule: "Host(`hook.example.com`)"
      traefik.http.routers.telegramhook.entrypoints: "websecure"
      traefik.http.routers.telegramhook.tls: "true"

Update the hostnames/entrypoints as needed and ensure the proxy network exists:

docker network create proxy

Then boot the stack (with a populated .env file):

docker compose up -d

🔐 Telegram Login Flow

1. Supply your phone number in the UI and send a verification code.
2. Enter the code (and optional 2FA password) to complete the sign-in.
3. The session file is stored at TELEGRAM_SESSION_PATH; persist it (e.g., volume mount /data).
4. Once authorized, hitting GET /action/{hook_id} triggers the configured message.

📡 HTTP Endpoints (excerpt)

• GET / – Single-page dashboard.
• GET /api/status – Telegram session state.
• POST /api/login/start – Send login code to phone.
• POST /api/login/verify – Finish login with code (+ optional password).
• POST /api/hooks – Create a hook { chat_id, message }.
• GET /api/hooks – List hooks with action URLs.
• DELETE /api/hooks/{hook_id} – Remove a hook.
• GET /action/{hook_id} – Trigger message delivery.

📝 Notes & Next Steps

• Messages accept Markdown (Telethon md) and multi-line content.
• The UI surfaces the generated action URL and offers quick copy/delete controls.
• Consider enabling HTTPS on Traefik (e.g., via ACME) before exposing publicly.
• For production, store the /data volume on persistent storage and secure the host with a firewall.