Add Telegram notification integration for geofencing
Features: - Multi-channel notifications (Email + Telegram) - User-configurable notification settings per channel - Telegram bot integration with rich messages, location pins, and inline buttons - QR code generation for easy bot access (@myidbot support) - Admin UI for notification settings management - Test functionality for Telegram connection - Comprehensive documentation Implementation: - lib/telegram-service.ts: Telegram API integration - lib/notification-settings-db.ts: Database layer for user notification preferences - lib/geofence-notifications.ts: Extended for parallel multi-channel delivery - API routes for settings management and testing - Admin UI with QR code display and step-by-step instructions - Database table: UserNotificationSettings Documentation: - docs/telegram.md: Technical implementation guide - docs/telegram-anleitung.md: User guide with @myidbot instructions - docs/telegram-setup.md: Admin setup guide - README.md: Updated NPM scripts section Docker: - Updated Dockerfile to copy public directory - Added TELEGRAM_BOT_TOKEN environment variable - Integrated notification settings initialization in db:init 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
163
docs/telegram-anleitung.md
Normal file
163
docs/telegram-anleitung.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 📱 Telegram-Benachrichtigungen aktivieren
|
||||
|
||||
## Übersicht
|
||||
|
||||
Erhalte Geofence-Benachrichtigungen direkt in Telegram mit:
|
||||
- 📍 Standort-Pin auf der Karte
|
||||
- 🔔 Sofortige Push-Benachrichtigungen
|
||||
- 🔗 Direktlinks zur Karte und zum Dashboard
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Schritt-für-Schritt Anleitung
|
||||
|
||||
### Schritt 1: Bot starten
|
||||
|
||||
#### Option A: QR-Code scannen (empfohlen für Smartphone)
|
||||
|
||||
<p align="center">
|
||||
<img src="../public/telegram-bot-qr.png" width="300" alt="Telegram Bot QR Code">
|
||||
</p>
|
||||
|
||||
1. Öffne die Kamera-App auf deinem Smartphone
|
||||
2. Scanne den QR-Code
|
||||
3. Telegram öffnet sich automatisch
|
||||
4. Klicke auf **"Start"** oder sende `/start`
|
||||
|
||||
#### Option B: Link öffnen
|
||||
|
||||
1. Klicke auf: **[https://t.me/MeinTracking_bot](https://t.me/MeinTracking_bot)**
|
||||
2. Telegram öffnet sich automatisch
|
||||
3. Klicke auf **"Start"** oder sende `/start`
|
||||
|
||||
✅ Du solltest eine Willkommensnachricht vom Bot erhalten
|
||||
|
||||
---
|
||||
|
||||
### Schritt 2: Chat ID herausfinden
|
||||
|
||||
#### Option A: Mit @myidbot (empfohlen)
|
||||
|
||||
1. Suche in Telegram nach: **@myidbot**
|
||||
2. Sende: `/getid`
|
||||
3. Der Bot antwortet sofort mit deiner Chat ID:
|
||||
```
|
||||
Your user ID: 123456789
|
||||
```
|
||||
4. **Kopiere die Nummer** (z.B. `123456789`)
|
||||
|
||||
#### Option B: Mit @userinfobot
|
||||
|
||||
1. Suche in Telegram nach: **@userinfobot**
|
||||
2. Sende: `/start`
|
||||
3. Der Bot antwortet mit deinen Informationen:
|
||||
```
|
||||
Id: 123456789
|
||||
First name: Dein Name
|
||||
...
|
||||
```
|
||||
4. **Kopiere die Nummer** bei "Id:" (z.B. `123456789`)
|
||||
|
||||
---
|
||||
|
||||
### Schritt 3: Chat ID im Dashboard eintragen
|
||||
|
||||
1. Melde dich im Location Tracker an
|
||||
2. Gehe zu: **Einstellungen** → **Benachrichtigungen**
|
||||
3. Aktiviere: ☑️ **Telegram Benachrichtigungen**
|
||||
4. Trage deine **Chat ID** ein (die Nummer aus Schritt 2)
|
||||
5. Klicke auf **"Speichern"**
|
||||
|
||||
---
|
||||
|
||||
### Schritt 4: Verbindung testen
|
||||
|
||||
1. Klicke auf den Button **"Telegram Test"**
|
||||
2. Du solltest sofort eine Test-Nachricht in Telegram erhalten:
|
||||
```
|
||||
✅ Telegram Connection Test
|
||||
|
||||
Die Verbindung funktioniert!
|
||||
```
|
||||
|
||||
✅ **Fertig!** Ab jetzt erhältst du alle Geofence-Benachrichtigungen auch per Telegram.
|
||||
|
||||
---
|
||||
|
||||
## 📨 Beispiel-Benachrichtigung
|
||||
|
||||
So sieht eine Geofence-Benachrichtigung aus:
|
||||
|
||||
```
|
||||
🟢 Geofence BETRETEN
|
||||
|
||||
📱 Device: Mein iPhone
|
||||
📍 Geofence: Zuhause
|
||||
🕐 Zeit: 04.12.25, 14:30
|
||||
📊 Ereignis: Hat Zuhause betreten
|
||||
```
|
||||
|
||||
**+ Standort-Pin auf der Karte**
|
||||
|
||||
**+ Buttons:**
|
||||
- 🗺️ Auf Karte zeigen
|
||||
- 📊 Dashboard öffnen
|
||||
|
||||
---
|
||||
|
||||
## ❓ Häufige Fragen
|
||||
|
||||
### Kann ich sowohl Email als auch Telegram aktivieren?
|
||||
|
||||
Ja! Du kannst beide Kanäle gleichzeitig nutzen:
|
||||
- ☑️ E-Mail Benachrichtigungen
|
||||
- ☑️ Telegram Benachrichtigungen
|
||||
|
||||
### Sehen andere User meine Benachrichtigungen?
|
||||
|
||||
**Nein!** Jede Chat ID ist ein privater 1-zu-1 Chat. Andere User können deine Nachrichten nicht sehen, auch wenn sie den gleichen Bot nutzen.
|
||||
|
||||
### Was ist, wenn die Chat ID falsch ist?
|
||||
|
||||
Dann erhältst du keine Benachrichtigungen. Nutze den "Telegram Test" Button, um die Verbindung zu prüfen.
|
||||
|
||||
### Kann ich Benachrichtigungen pausieren?
|
||||
|
||||
Ja! Deaktiviere einfach "Telegram Benachrichtigungen" in den Einstellungen. Deine Chat ID bleibt gespeichert.
|
||||
|
||||
### Wo finde ich meine Chat ID nochmal?
|
||||
|
||||
Sende `/getid` an **@myidbot** oder `/start` an **@userinfobot** in Telegram.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### "No Telegram chat ID configured"
|
||||
|
||||
→ Du hast noch keine Chat ID eingetragen. Folge Schritt 2 und 3.
|
||||
|
||||
### "Failed to send test message"
|
||||
|
||||
Mögliche Ursachen:
|
||||
1. **Chat ID falsch** → Überprüfe die Nummer bei @userinfobot
|
||||
2. **Bot nicht gestartet** → Sende `/start` an @MeinTracking_bot
|
||||
3. **Bot blockiert** → Entsperre den Bot in Telegram
|
||||
|
||||
### Test-Nachricht kommt nicht an
|
||||
|
||||
1. Überprüfe, ob du den Bot gestartet hast (`/start` an @MeinTracking_bot)
|
||||
2. Prüfe, ob die Chat ID korrekt ist (keine Leerzeichen, keine Buchstaben)
|
||||
- Hole sie neu mit `/getid` an @myidbot
|
||||
3. Stelle sicher, dass du den Bot nicht blockiert hast
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
Bei Problemen wende dich an den Administrator oder überprüfe die Logs im System.
|
||||
|
||||
---
|
||||
|
||||
**Bot:** [@MeinTracking_bot](https://t.me/MeinTracking_bot)
|
||||
**Letzte Aktualisierung:** 04.12.2025
|
||||
345
docs/telegram-setup.md
Normal file
345
docs/telegram-setup.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 🚀 Telegram Integration - Setup Guide
|
||||
|
||||
## ✅ Was wurde implementiert
|
||||
|
||||
### Dateien erstellt:
|
||||
|
||||
1. **Backend Services:**
|
||||
- `lib/telegram-service.ts` - Telegram API Integration
|
||||
- `lib/notification-settings-db.ts` - Datenbank-Layer für Settings
|
||||
- `lib/geofence-notifications.ts` - Erweitert für Multi-Channel (Email + Telegram)
|
||||
|
||||
2. **Database:**
|
||||
- `scripts/init-notification-settings.js` - DB Init Script
|
||||
- Tabelle: `UserNotificationSettings` erstellt
|
||||
|
||||
3. **API Endpoints:**
|
||||
- `GET/PATCH /api/users/[id]/notification-settings` - Settings verwalten
|
||||
- `POST /api/users/[id]/notification-settings/test` - Test-Nachricht
|
||||
|
||||
4. **Admin UI:**
|
||||
- `app/admin/settings/notifications/page.tsx` - Settings Page mit QR Code
|
||||
|
||||
5. **Dokumentation:**
|
||||
- `docs/telegram-anleitung.md` - User-Anleitung
|
||||
- `docs/telegram-setup.md` - Dieses Dokument
|
||||
- `public/telegram-bot-qr.png` - QR Code für Bot
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Installation & Setup
|
||||
|
||||
### 1. Dependencies installiert
|
||||
|
||||
```bash
|
||||
✅ npm install axios
|
||||
✅ npm install qrcode
|
||||
```
|
||||
|
||||
### 2. Datenbank initialisiert
|
||||
|
||||
```bash
|
||||
✅ node scripts/init-notification-settings.js
|
||||
```
|
||||
|
||||
Die Tabelle `UserNotificationSettings` wurde erstellt mit:
|
||||
- `user_id` (PK, FK → User.id)
|
||||
- `email_enabled` (0/1)
|
||||
- `telegram_enabled` (0/1)
|
||||
- `telegram_chat_id` (TEXT)
|
||||
- `created_at`, `updated_at`
|
||||
|
||||
---
|
||||
|
||||
## 📱 Bot Setup
|
||||
|
||||
### Telegram Bot erstellen (für Admin):
|
||||
|
||||
1. Öffne Telegram und suche: **@BotFather**
|
||||
2. Sende: `/newbot`
|
||||
3. Folge den Anweisungen:
|
||||
- Bot Name: `MeinTracking Bot` (oder anders)
|
||||
- Bot Username: `MeinTracking_bot` (muss auf `_bot` enden)
|
||||
4. BotFather gibt dir einen Token: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`
|
||||
5. **Wichtig:** Token NIEMALS committen!
|
||||
|
||||
### .env konfigurieren:
|
||||
|
||||
```bash
|
||||
# .env oder .env.local
|
||||
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Für User: Bot aktivieren
|
||||
|
||||
**Schritt-für-Schritt siehe:** `docs/telegram-anleitung.md`
|
||||
|
||||
**Kurzversion:**
|
||||
1. Bot starten: [https://t.me/MeinTracking_bot](https://t.me/MeinTracking_bot) oder QR scannen
|
||||
2. Chat ID holen: `@myidbot` → `/getid` (oder `@userinfobot` → `/start`)
|
||||
3. Im Dashboard: Settings → Notifications → Chat ID eintragen
|
||||
4. Test Button drücken
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### 1. QR Code generieren
|
||||
|
||||
```bash
|
||||
npm run telegram:qr
|
||||
```
|
||||
|
||||
Erstellt: `public/telegram-bot-qr.png`
|
||||
|
||||
### 2. Datenbank neu initialisieren
|
||||
|
||||
```bash
|
||||
npm run db:init:notifications
|
||||
```
|
||||
|
||||
Oder alles zusammen:
|
||||
```bash
|
||||
npm run db:init
|
||||
```
|
||||
|
||||
### 3. Test-Nachricht senden
|
||||
|
||||
**Option A: Über Admin UI**
|
||||
- Navigiere zu: `/admin/settings/notifications`
|
||||
- Telegram aktivieren
|
||||
- Chat ID eintragen
|
||||
- Button "Telegram Test" klicken
|
||||
|
||||
**Option B: Direkt via Script**
|
||||
|
||||
Erstelle `scripts/test-telegram.js`:
|
||||
```javascript
|
||||
const { telegramService } = require('../lib/telegram-service');
|
||||
|
||||
const CHAT_ID = '123456789'; // Deine Chat ID
|
||||
|
||||
async function test() {
|
||||
await telegramService.testConnection(CHAT_ID);
|
||||
}
|
||||
test();
|
||||
```
|
||||
|
||||
```bash
|
||||
TELEGRAM_BOT_TOKEN=dein_token node scripts/test-telegram.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Sicherheit & Privacy
|
||||
|
||||
### Wie funktioniert die Privacy?
|
||||
|
||||
- **1 Bot für alle User** (in `.env`)
|
||||
- **Jeder User hat eigene Chat ID** (in DB)
|
||||
- **Bot sendet nur an spezifische Chat ID** → Privater 1-zu-1 Chat
|
||||
- **User A sieht NIEMALS Nachrichten von User B**
|
||||
|
||||
### Telegram API Garantie:
|
||||
|
||||
```typescript
|
||||
telegram.sendMessage(chatId: "123456789", text: "...")
|
||||
→ Geht NUR an Chat ID 123456789
|
||||
→ Andere Chat IDs können dies NICHT sehen
|
||||
```
|
||||
|
||||
### Vergleich:
|
||||
Wie Email: 1 SMTP-Server (Bot) sendet an verschiedene Adressen (Chat IDs)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Wie es funktioniert
|
||||
|
||||
### Notification Flow:
|
||||
|
||||
```
|
||||
1. Device triggers Geofence
|
||||
↓
|
||||
2. geofence-engine.ts erkennt Event
|
||||
↓
|
||||
3. GeofenceEvent in DB erstellt
|
||||
↓
|
||||
4. geofence-notifications.ts aufgerufen
|
||||
↓
|
||||
5. getUserNotificationSettings(owner_id)
|
||||
↓
|
||||
6. Parallel execution:
|
||||
├─→ Email (if enabled)
|
||||
└─→ Telegram (if enabled)
|
||||
↓
|
||||
├─→ Text mit Emoji, Device, Geofence, Zeit
|
||||
├─→ Inline Buttons (Karte, Dashboard)
|
||||
└─→ Location Pin
|
||||
```
|
||||
|
||||
### Multi-Channel Strategy:
|
||||
|
||||
- **Promise.allSettled()** → Beide parallel
|
||||
- **Mind. 1 erfolgreich** → Event als "sent" markiert
|
||||
- **Beide fehlgeschlagen** → Event als "failed" markiert
|
||||
- **Robust:** Email-Fehler betrifft nicht Telegram (und umgekehrt)
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Admin UI Features
|
||||
|
||||
**Page:** `/admin/settings/notifications`
|
||||
|
||||
**Komponenten:**
|
||||
- ☑️ Email Benachrichtigungen Toggle
|
||||
- ☑️ Telegram Benachrichtigungen Toggle
|
||||
- 📝 Telegram Chat ID Input
|
||||
- 💾 Speichern Button
|
||||
- 🧪 Telegram Test Button
|
||||
- 📱 QR Code Display (400x400px)
|
||||
- 📖 Schritt-für-Schritt Anleitung
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ NPM Scripts
|
||||
|
||||
```bash
|
||||
# Datenbank initialisieren
|
||||
npm run db:init # Alles (inkl. Notifications)
|
||||
npm run db:init:notifications # Nur Notifications Tabelle
|
||||
|
||||
# QR Code generieren
|
||||
npm run telegram:qr # Erstellt public/telegram-bot-qr.png
|
||||
|
||||
# Testing
|
||||
npm run test:geofence # Geofence Event simulieren
|
||||
npm run test:geofence:email # Email Notification testen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Telegram Message Format
|
||||
|
||||
### Enter Event:
|
||||
```
|
||||
🟢 Geofence BETRETEN
|
||||
|
||||
📱 Device: Mein iPhone
|
||||
📍 Geofence: Zuhause
|
||||
🕐 Zeit: 04.12.25, 14:30
|
||||
📊 Ereignis: Hat Zuhause betreten
|
||||
```
|
||||
|
||||
**+ Location Pin** (Karte mit exakter Position)
|
||||
|
||||
**+ Buttons:**
|
||||
- 🗺️ Auf Karte zeigen → `/map?lat=...&lon=...`
|
||||
- 📊 Dashboard öffnen → `/admin/geofences/events`
|
||||
|
||||
### Exit Event:
|
||||
```
|
||||
🔴 Geofence VERLASSEN
|
||||
|
||||
📱 Device: Mein iPhone
|
||||
📍 Geofence: Zuhause
|
||||
🕐 Zeit: 04.12.25, 18:45
|
||||
📊 Ereignis: Hat Zuhause verlassen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### "Cannot find module telegram-service"
|
||||
|
||||
→ TypeScript nicht kompiliert. Lösung:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Oder für Development:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### "Telegram bot token not configured"
|
||||
|
||||
→ `.env` fehlt `TELEGRAM_BOT_TOKEN`
|
||||
|
||||
### "Failed to send test message"
|
||||
|
||||
**Mögliche Ursachen:**
|
||||
1. Bot nicht gestartet (`/start` an @MeinTracking_bot)
|
||||
2. Chat ID falsch
|
||||
3. Bot blockiert
|
||||
4. Token falsch/abgelaufen
|
||||
|
||||
**Debug:**
|
||||
```bash
|
||||
# Check .env
|
||||
cat .env | grep TELEGRAM
|
||||
|
||||
# Check DB
|
||||
sqlite3 data/database.sqlite "SELECT * FROM UserNotificationSettings;"
|
||||
|
||||
# Test Telegram API direkt
|
||||
curl https://api.telegram.org/bot<TOKEN>/getMe
|
||||
```
|
||||
|
||||
### QR Code wird nicht angezeigt
|
||||
|
||||
→ Prüfen ob Datei existiert:
|
||||
```bash
|
||||
ls -la public/telegram-bot-qr.png
|
||||
```
|
||||
|
||||
Falls nicht:
|
||||
```bash
|
||||
npm run telegram:qr
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Environment Variables
|
||||
|
||||
```bash
|
||||
# Required für Telegram
|
||||
TELEGRAM_BOT_TOKEN=<dein_bot_token>
|
||||
|
||||
# Optional (für Map/Dashboard Links)
|
||||
NEXTAUTH_URL=https://deine-domain.de
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Nächste Schritte
|
||||
|
||||
**Für Produktion:**
|
||||
|
||||
1. ✅ `.env.production` mit echtem Bot-Token erstellen
|
||||
2. ✅ Datenbank migrieren: `npm run db:init`
|
||||
3. ✅ QR Code generieren: `npm run telegram:qr`
|
||||
4. ✅ User-Anleitung teilen: `docs/telegram-anleitung.md`
|
||||
5. ✅ Test durchführen mit echtem Device
|
||||
|
||||
**Optional:**
|
||||
- Push Notifications hinzufügen
|
||||
- SMS Integration
|
||||
- Webhook Support
|
||||
- Notification History UI
|
||||
- Per-Geofence Settings (nicht global)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
**Bot:** [@MeinTracking_bot](https://t.me/MeinTracking_bot)
|
||||
|
||||
**Dokumentation:**
|
||||
- User-Anleitung: `docs/telegram-anleitung.md`
|
||||
- API Implementierung: `docs/telegram.md`
|
||||
- Dieses Setup-Guide: `docs/telegram-setup.md`
|
||||
|
||||
**Letzte Aktualisierung:** 04.12.2025
|
||||
1162
docs/telegram.md
Normal file
1162
docs/telegram.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user