location-mqtt-tracker-app/docs/telegram-setup.md

🚀 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

✅ npm install axios
✅ npm install qrcode

2. Datenbank initialisiert

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

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

npm run telegram:qr

Erstellt: public/telegram-bot-qr.png

2. Datenbank neu initialisieren

npm run db:init:notifications

Oder alles zusammen:

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:

const { telegramService } = require('../lib/telegram-service');

const CHAT_ID = '123456789'; // Deine Chat ID

async function test() {
  await telegramService.testConnection(CHAT_ID);
}
test();

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:

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

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

npm run build

Oder für Development:

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:

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

ls -la public/telegram-bot-qr.png

Falls nicht:

npm run telegram:qr

---

📚 Environment Variables

# 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

Dokumentation:

• User-Anleitung: docs/telegram-anleitung.md
• API Implementierung: docs/telegram.md
• Dieses Setup-Guide: docs/telegram-setup.md

Letzte Aktualisierung: 04.12.2025