# 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:

```powershell
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:

```powershell
pip install -r requirements-dev.txt
```

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

```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:

```powershell
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):

```powershell
python -m pytest
```

## 🐳 Docker

Build the image:

```powershell
docker build -t telegram-hook .
```

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

```powershell
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`:

```yaml
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:

```powershell
docker network create proxy
```

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

```powershell
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.