143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# 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.
|