feat: Add Telegram Bot standalone test (Phase 1)
- Add FEATURE_PLAN-telegram.md with 6-phase implementation roadmap - Add scripts/README.telegram.md with step-by-step setup guide - Add scripts/telegram-test.js standalone test script - Add scripts/.env.telegram.example template for credentials - Update .gitignore to protect Telegram credentials Phase 1 complete: Bot setup, privacy mode configuration, and successful test message delivery.
This commit is contained in:
parent
b2386e7f11
commit
86ace42fca
5
.gitignore
vendored
5
.gitignore
vendored
|
|
@ -9,6 +9,11 @@ node_modules/
|
|||
.env
|
||||
.env.local
|
||||
|
||||
# Telegram credentials
|
||||
scripts/.env.telegram
|
||||
scripts/node_modules/
|
||||
scripts/package-lock.json
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
|
|
|
|||
358
FeatureRequests/FEATURE_PLAN-telegram.md
Normal file
358
FeatureRequests/FEATURE_PLAN-telegram.md
Normal file
|
|
@ -0,0 +1,358 @@
|
|||
# Feature Plan: Telegram Bot Integration
|
||||
|
||||
## Übersicht
|
||||
|
||||
Implementierung eines Telegram Bots zur automatischen Benachrichtigung der Werkstatt-Gruppe über wichtige Events im Image Uploader System.
|
||||
|
||||
**Basis:** [FEATURE_REQUEST-telegram.md](./FEATURE_REQUEST-telegram.md)
|
||||
|
||||
---
|
||||
|
||||
## Phasen-Aufteilung
|
||||
|
||||
### Phase 1: Bot Setup & Standalone-Test ⭐ **CURRENT**
|
||||
**Ziel:** Telegram Bot erstellen und isoliert testen (ohne App-Integration)
|
||||
|
||||
**Status:** 🟡 In Planung
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Telegram Bot via BotFather erstellt
|
||||
- [ ] Bot zu Test-Telegram-Gruppe hinzugefügt
|
||||
- [ ] Chat-ID ermittelt
|
||||
- [ ] `scripts/telegram-test.js` - Standalone Test-Script
|
||||
- [ ] `scripts/README.telegram.md` - Setup-Anleitung
|
||||
- [ ] `.env.telegram` - Template für Bot-Credentials
|
||||
- [ ] Erfolgreiche Test-Nachricht versendet
|
||||
|
||||
**Akzeptanzkriterium:**
|
||||
✅ Bot sendet erfolgreich Nachricht an Testgruppe
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Backend-Service Integration
|
||||
**Ziel:** TelegramNotificationService in Backend integrieren
|
||||
|
||||
**Dependencies:** Phase 1 abgeschlossen
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] `backend/src/services/TelegramNotificationService.js`
|
||||
- [ ] ENV-Variablen in `docker/dev/backend/config/.env`
|
||||
- [ ] Unit-Tests für Service
|
||||
- [ ] Docker Dev Environment funktioniert
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Upload-Benachrichtigungen
|
||||
**Ziel:** Automatische Benachrichtigungen bei neuem Upload
|
||||
|
||||
**Dependencies:** Phase 2 abgeschlossen
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Integration in `routes/batchUpload.js`
|
||||
- [ ] `sendUploadNotification()` Methode
|
||||
- [ ] Formatierung mit Icons/Emojis
|
||||
- [ ] Integration-Tests
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: User-Änderungs-Benachrichtigungen
|
||||
**Ziel:** Benachrichtigungen bei Consent-Änderungen & Löschungen
|
||||
|
||||
**Dependencies:** Phase 3 abgeschlossen
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Integration in `routes/management.js` (PUT/DELETE)
|
||||
- [ ] `sendConsentChangeNotification()` Methode
|
||||
- [ ] `sendGroupDeletedNotification()` Methode
|
||||
- [ ] Integration-Tests
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Tägliche Lösch-Warnungen
|
||||
**Ziel:** Cron-Job für bevorstehende Löschungen
|
||||
|
||||
**Dependencies:** Phase 4 abgeschlossen
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Cron-Job Setup (node-cron)
|
||||
- [ ] `sendDeletionWarning()` Methode
|
||||
- [ ] Admin-Route für manuellen Trigger
|
||||
- [ ] Dokumentation
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Production Deployment
|
||||
**Ziel:** Rollout in Production-Umgebung
|
||||
|
||||
**Dependencies:** Phase 1-5 abgeschlossen + getestet
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Production ENV-Variablen
|
||||
- [ ] Docker Prod Environment konfiguriert
|
||||
- [ ] Bot in echte Werkstatt-Gruppe eingefügt
|
||||
- [ ] Monitoring/Logging
|
||||
- [ ] README.md Update
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 - Detaillierter Plan
|
||||
|
||||
### 1. Vorbereitung (5 min)
|
||||
|
||||
**Auf Windows 11 Host-System:**
|
||||
|
||||
```bash
|
||||
# Node.js Version prüfen
|
||||
node --version # Sollte >= 18.x sein
|
||||
|
||||
# Projektverzeichnis öffnen
|
||||
cd /home/lotzm/gitea.hobbyhimmel/Project-Image-Uploader/scripts
|
||||
|
||||
# Dependencies installieren (lokal)
|
||||
npm init -y # Falls noch keine package.json
|
||||
npm install node-telegram-bot-api dotenv
|
||||
```
|
||||
|
||||
### 2. Telegram Bot erstellen (10 min)
|
||||
|
||||
**Anleitung:** Siehe `scripts/README.telegram.md`
|
||||
|
||||
**Schritte:**
|
||||
1. Telegram öffnen (Windows 11 App)
|
||||
2. [@BotFather](https://t.me/botfather) suchen
|
||||
3. `/newbot` Command
|
||||
4. Bot-Name: "Werkstatt Image Uploader Bot"
|
||||
5. Username: `werkstatt_uploader_bot` (oder verfügbar)
|
||||
6. **Token kopieren** → `.env.telegram`
|
||||
|
||||
### 3. Test-Gruppe erstellen & Bot hinzufügen (5 min)
|
||||
|
||||
**Schritte:**
|
||||
1. Neue Telegram-Gruppe erstellen: "Werkstatt Upload Bot Test"
|
||||
2. Bot zur Gruppe hinzufügen: @werkstatt_uploader_bot
|
||||
3. **Chat-ID ermitteln** (siehe README.telegram.md)
|
||||
4. Chat-ID speichern → `.env.telegram`
|
||||
|
||||
### 4. Test-Script erstellen (10 min)
|
||||
|
||||
**Datei:** `scripts/telegram-test.js`
|
||||
|
||||
**Features:**
|
||||
- Lädt `.env.telegram`
|
||||
- Validiert Bot-Token
|
||||
- Sendet Test-Nachricht
|
||||
- Error-Handling
|
||||
|
||||
### 5. Erste Nachricht senden (2 min)
|
||||
|
||||
```bash
|
||||
cd scripts
|
||||
node telegram-test.js
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe:**
|
||||
```
|
||||
✅ Telegram Bot erfolgreich verbunden!
|
||||
Bot-Name: Werkstatt Image Uploader Bot
|
||||
Bot-Username: @werkstatt_uploader_bot
|
||||
|
||||
📤 Sende Test-Nachricht an Chat -1001234567890...
|
||||
✅ Nachricht erfolgreich gesendet!
|
||||
```
|
||||
|
||||
**In Telegram-Gruppe:**
|
||||
```
|
||||
🤖 Telegram Bot Test
|
||||
|
||||
Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot.
|
||||
|
||||
Status: ✅ Erfolgreich verbunden!
|
||||
Zeitstempel: 2025-11-29 14:23:45
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dateistruktur (Phase 1)
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── README.telegram.md # Setup-Anleitung (NEU)
|
||||
├── telegram-test.js # Test-Script (NEU)
|
||||
├── .env.telegram.example # ENV-Template (NEU)
|
||||
├── .env.telegram # Echte Credentials (gitignored, NEU)
|
||||
├── package.json # Lokale Dependencies (NEU)
|
||||
└── node_modules/ # npm packages (gitignored)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables (Phase 1)
|
||||
|
||||
**Datei:** `scripts/.env.telegram`
|
||||
|
||||
```bash
|
||||
# Telegram Bot Configuration
|
||||
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
TELEGRAM_CHAT_ID=-1001234567890
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies (Phase 1)
|
||||
|
||||
**Package:** `scripts/package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "telegram-test-scripts",
|
||||
"version": "1.0.0",
|
||||
"description": "Standalone Telegram Bot Testing",
|
||||
"main": "telegram-test.js",
|
||||
"scripts": {
|
||||
"test": "node telegram-test.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"node-telegram-bot-api": "^0.66.0",
|
||||
"dotenv": "^16.3.1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sicherheit (Phase 1)
|
||||
|
||||
**`.gitignore` ergänzen:**
|
||||
|
||||
```
|
||||
# Telegram Credentials
|
||||
scripts/.env.telegram
|
||||
scripts/node_modules/
|
||||
scripts/package-lock.json
|
||||
```
|
||||
|
||||
**Wichtig:**
|
||||
- ❌ Niemals `.env.telegram` committen!
|
||||
- ✅ Nur `.env.telegram.example` (ohne echte Tokens) committen
|
||||
- ✅ Bot-Token regenerieren, falls versehentlich exposed
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist (Phase 1)
|
||||
|
||||
- [ ] Node.js Version >= 18.x
|
||||
- [ ] Telegram App installiert (Windows 11)
|
||||
- [ ] Bot via BotFather erstellt
|
||||
- [ ] Bot-Token gespeichert in `.env.telegram`
|
||||
- [ ] Test-Gruppe erstellt
|
||||
- [ ] Bot zur Gruppe hinzugefügt
|
||||
- [ ] Chat-ID ermittelt
|
||||
- [ ] Chat-ID gespeichert in `.env.telegram`
|
||||
- [ ] `npm install` erfolgreich
|
||||
- [ ] `node telegram-test.js` läuft ohne Fehler
|
||||
- [ ] Test-Nachricht in Telegram-Gruppe empfangen
|
||||
- [ ] Formatierung (Emojis, Zeilenumbrüche) korrekt
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting (Phase 1)
|
||||
|
||||
### Problem: "Unauthorized (401)"
|
||||
**Lösung:** Bot-Token falsch → BotFather prüfen, `.env.telegram` korrigieren
|
||||
|
||||
### Problem: "Bad Request: chat not found"
|
||||
**Lösung:** Chat-ID falsch → Neue Nachricht in Gruppe senden, Chat-ID neu ermitteln
|
||||
|
||||
### Problem: "ETELEGRAM: 403 Forbidden"
|
||||
**Lösung:** Bot wurde aus Gruppe entfernt → Bot erneut zur Gruppe hinzufügen
|
||||
|
||||
### Problem: "Module not found: node-telegram-bot-api"
|
||||
**Lösung:**
|
||||
```bash
|
||||
cd scripts
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Nächste Schritte (nach Phase 1)
|
||||
|
||||
1. **Code-Review:** `scripts/telegram-test.js`
|
||||
2. **Dokumentation Review:** `scripts/README.telegram.md`
|
||||
3. **Commit:**
|
||||
```bash
|
||||
git add scripts/
|
||||
git commit -m "feat: Add Telegram Bot standalone test (Phase 1)"
|
||||
```
|
||||
4. **Phase 2 starten:** Backend-Integration planen
|
||||
|
||||
---
|
||||
|
||||
## Zeitschätzung
|
||||
|
||||
| Phase | Aufwand | Beschreibung |
|
||||
|-------|---------|--------------|
|
||||
| **Phase 1** | **~45 min** | Bot Setup + Standalone-Test |
|
||||
| Phase 2 | ~2h | Backend-Service |
|
||||
| Phase 3 | ~2h | Upload-Benachrichtigungen |
|
||||
| Phase 4 | ~2h | Änderungs-Benachrichtigungen |
|
||||
| Phase 5 | ~2h | Cron-Job |
|
||||
| Phase 6 | ~1h | Production Deployment |
|
||||
| **Gesamt** | **~9-10h** | Vollständige Integration |
|
||||
|
||||
---
|
||||
|
||||
## Conventional Commits (ab Phase 1)
|
||||
|
||||
**Phase 1:**
|
||||
```bash
|
||||
git commit -m "feat: Add Telegram Bot test script"
|
||||
git commit -m "docs: Add Telegram Bot setup guide"
|
||||
git commit -m "chore: Add node-telegram-bot-api dependency to scripts"
|
||||
```
|
||||
|
||||
**Phase 2:**
|
||||
```bash
|
||||
git commit -m "feat: Add TelegramNotificationService"
|
||||
git commit -m "test: Add TelegramNotificationService unit tests"
|
||||
```
|
||||
|
||||
**Phase 3-6:**
|
||||
```bash
|
||||
git commit -m "feat: Add upload notification to Telegram"
|
||||
git commit -m "feat: Add consent change notifications"
|
||||
git commit -m "feat: Add daily deletion warnings cron job"
|
||||
git commit -m "docs: Update README with Telegram features"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release-Planung
|
||||
|
||||
**Phase 1:** Kein Release (interne Tests)
|
||||
|
||||
**Phase 6 (Final):**
|
||||
- **Version:** `2.0.0` (Major Release)
|
||||
- **Branch:** `feature/telegram-notifications`
|
||||
- **Release-Command:** `npm run release:major`
|
||||
|
||||
---
|
||||
|
||||
## Status-Tracking
|
||||
|
||||
**Letzte Aktualisierung:** 2025-11-29
|
||||
|
||||
| Phase | Status | Datum |
|
||||
|-------|--------|-------|
|
||||
| Phase 1 | 🟡 In Planung | 2025-11-29 |
|
||||
| Phase 2 | ⚪ Ausstehend | - |
|
||||
| Phase 3 | ⚪ Ausstehend | - |
|
||||
| Phase 4 | ⚪ Ausstehend | - |
|
||||
| Phase 5 | ⚪ Ausstehend | - |
|
||||
| Phase 6 | ⚪ Ausstehend | - |
|
||||
|
||||
**Legende:**
|
||||
- 🟢 Abgeschlossen
|
||||
- 🟡 In Arbeit
|
||||
- 🔴 Blockiert
|
||||
- ⚪ Ausstehend
|
||||
15
scripts/.env.telegram.example
Normal file
15
scripts/.env.telegram.example
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# Telegram Bot Configuration Template
|
||||
#
|
||||
# Kopiere diese Datei zu .env.telegram und trage deine echten Werte ein:
|
||||
# cp .env.telegram.example .env.telegram
|
||||
#
|
||||
# WICHTIG: .env.telegram NIEMALS committen! (ist in .gitignore)
|
||||
|
||||
# Bot-Token von @BotFather
|
||||
# Beispiel: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890
|
||||
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE
|
||||
|
||||
# Chat-ID der Telegram-Gruppe (negativ für Gruppen!)
|
||||
# Ermitteln via: https://api.telegram.org/bot<TOKEN>/getUpdates
|
||||
# Beispiel: -1001234567890
|
||||
TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE
|
||||
506
scripts/README.telegram.md
Normal file
506
scripts/README.telegram.md
Normal file
|
|
@ -0,0 +1,506 @@
|
|||
# Telegram Bot Setup & Testing Guide
|
||||
|
||||
## Übersicht
|
||||
|
||||
Diese Anleitung beschreibt Schritt-für-Schritt, wie du den Telegram Bot für den Image Uploader erstellst und testest.
|
||||
|
||||
**Phase 1:** Standalone-Test (ohne Backend-Integration)
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- ✅ Windows 11 mit installiertem Telegram Desktop
|
||||
- ✅ Telegram Account
|
||||
- ✅ Node.js >= 18.x installiert
|
||||
- ✅ Zugriff auf dieses Git-Repository
|
||||
|
||||
---
|
||||
|
||||
## 1. Telegram Bot erstellen
|
||||
|
||||
### 1.1 BotFather öffnen
|
||||
|
||||
1. **Telegram Desktop** öffnen
|
||||
2. In der Suche eingeben: `@BotFather`
|
||||
3. Chat mit **BotFather** öffnen (offizieller Bot mit blauem Haken ✓)
|
||||
|
||||
### 1.2 Neuen Bot erstellen
|
||||
|
||||
**Commands im BotFather-Chat eingeben:**
|
||||
|
||||
```
|
||||
/newbot
|
||||
```
|
||||
|
||||
**BotFather fragt nach Namen:**
|
||||
```
|
||||
Alright, a new bot. How are we going to call it?
|
||||
Please choose a name for your bot.
|
||||
```
|
||||
|
||||
**Antworten mit:**
|
||||
```
|
||||
Werkstatt Image Uploader Bot
|
||||
```
|
||||
|
||||
**BotFather fragt nach Username:**
|
||||
```
|
||||
Good. Now let's choose a username for your bot.
|
||||
It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
|
||||
```
|
||||
|
||||
**Antworten mit (muss auf `bot` enden):**
|
||||
```
|
||||
werkstatt_uploader_bot
|
||||
```
|
||||
|
||||
⚠️ **Falls Username vergeben:** Anderen Namen wählen (z.B. `werkstatt_upload_bot`, `hobbyhimmel_uploader_bot`)
|
||||
|
||||
### 1.3 Bot-Token speichern
|
||||
|
||||
**BotFather antwortet mit:**
|
||||
```
|
||||
Done! Congratulations on your new bot.
|
||||
You will find it at t.me/werkstatt_uploader_bot.
|
||||
You can now add a description, about section and profile picture for your bot.
|
||||
|
||||
Use this token to access the HTTP API:
|
||||
123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890
|
||||
|
||||
Keep your token secure and store it safely, it can be used by anyone to control your bot.
|
||||
```
|
||||
|
||||
**Token kopieren** (z.B. `123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890`)
|
||||
|
||||
➡️ **Diesen Token brauchst du gleich für `.env.telegram`!**
|
||||
|
||||
---
|
||||
|
||||
## 2. Test-Telegram-Gruppe erstellen
|
||||
|
||||
### 2.1 Neue Gruppe erstellen
|
||||
|
||||
1. In Telegram: **Neuer Chat** → **Neue Gruppe**
|
||||
2. Gruppennamen eingeben: `Werkstatt Upload Bot Test`
|
||||
3. **Weiter** klicken
|
||||
4. (Optional) Weitere Mitglieder hinzufügen (oder nur dich selbst)
|
||||
5. **Erstellen** klicken
|
||||
|
||||
### 2.2 Bot zur Gruppe hinzufügen
|
||||
|
||||
1. Test-Gruppe öffnen
|
||||
2. Auf Gruppennamen (oben) klicken → **Mitglieder hinzufügen**
|
||||
3. Suche nach: `@werkstatt_uploader_bot` (dein Bot-Username)
|
||||
4. Bot auswählen → **Hinzufügen**
|
||||
|
||||
**Telegram zeigt:**
|
||||
```
|
||||
werkstatt_uploader_bot wurde zur Gruppe hinzugefügt
|
||||
```
|
||||
|
||||
### 2.3 Privacy Mode deaktivieren (WICHTIG!)
|
||||
|
||||
⚠️ **Ohne diesen Schritt sieht der Bot keine Gruppennachrichten!**
|
||||
|
||||
1. **BotFather** öffnen
|
||||
2. Command eingeben: `/mybots`
|
||||
3. Deinen Bot auswählen: `@werkstatt_uploader_bot`
|
||||
4. **Bot Settings** klicken
|
||||
5. **Group Privacy** klicken
|
||||
6. **Turn off** klicken
|
||||
|
||||
**BotFather bestätigt:**
|
||||
```
|
||||
Privacy mode is disabled for <bot-name>.
|
||||
All messages will now be sent to the bot.
|
||||
```
|
||||
|
||||
### 2.4 Bot als Admin hinzufügen (optional, aber empfohlen)
|
||||
|
||||
1. Gruppe öffnen → Gruppennamen klicken
|
||||
2. **Administratoren** → **Administrator hinzufügen**
|
||||
3. `@werkstatt_uploader_bot` auswählen
|
||||
4. **Berechtigungen:**
|
||||
- ✅ Nachrichten senden
|
||||
- ❌ Alle anderen optional (nicht nötig)
|
||||
5. **Speichern**
|
||||
|
||||
---
|
||||
|
||||
## 3. Chat-ID ermitteln
|
||||
|
||||
Die Chat-ID wird benötigt, um Nachrichten an die richtige Gruppe zu senden.
|
||||
|
||||
### Methode 1: Via Telegram API (empfohlen)
|
||||
|
||||
**Schritt 1:** Nachricht in Test-Gruppe senden
|
||||
|
||||
- Öffne die Test-Gruppe
|
||||
- Sende eine beliebige Nachricht (z.B. "Test")
|
||||
|
||||
**Schritt 2:** Browser öffnen und folgende URL aufrufen:
|
||||
|
||||
```
|
||||
https://api.telegram.org/bot<DEIN_BOT_TOKEN>/getUpdates
|
||||
```
|
||||
|
||||
**Ersetze `<DEIN_BOT_TOKEN>`** mit deinem echten Token!
|
||||
|
||||
**Beispiel:**
|
||||
```
|
||||
https://api.telegram.org/bot123456789:ABCdefGHIjklMNOpqrsTUVwxyz/getUpdates
|
||||
```
|
||||
|
||||
⚠️ **Wenn du `{"ok":true,"result":[]}` siehst (leeres result-Array):**
|
||||
|
||||
Das bedeutet, der Bot hat noch keine Nachrichten empfangen. **Checkliste:**
|
||||
|
||||
1. ✅ Hast du den Bot zur Gruppe hinzugefügt? (Schritt 2.2)
|
||||
2. ✅ Hast du **NACH** dem Hinzufügen eine Nachricht gesendet? (Schritt 1)
|
||||
3. ✅ War die Nachricht in der **richtigen Gruppe** (nicht im Bot-Direct-Chat)?
|
||||
|
||||
**Lösung - Mach jetzt folgendes:**
|
||||
- Telegram öffnen
|
||||
- **Test-Gruppe** öffnen (nicht den Bot direkt!)
|
||||
- Prüfe, ob der Bot als Mitglied angezeigt wird
|
||||
- Sende eine neue Nachricht: "Test"
|
||||
- **Sofort** zurück zum Browser → Seite neu laden (F5)
|
||||
|
||||
**Schritt 3:** Im JSON-Response nach `chat` suchen:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"result": [
|
||||
{
|
||||
"update_id": 123456789,
|
||||
"message": {
|
||||
"message_id": 1,
|
||||
"from": { ... },
|
||||
"chat": {
|
||||
"id": -1001234567890, // ← DAS IST DEINE CHAT-ID!
|
||||
"title": "Werkstatt Upload Bot Test",
|
||||
"type": "supergroup"
|
||||
},
|
||||
"text": "Test"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Chat-ID kopieren** (z.B. `-1001234567890`)
|
||||
|
||||
⚠️ **Wichtig:** Gruppen-Chat-IDs sind **negativ** und beginnen meist mit `-100`!
|
||||
|
||||
### Methode 2: Via curl (Linux/WSL)
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<DEIN_BOT_TOKEN>/getUpdates" | jq '.result[0].message.chat.id'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Environment-Datei erstellen
|
||||
|
||||
### 4.1 Template kopieren
|
||||
|
||||
```bash
|
||||
cd scripts
|
||||
cp .env.telegram.example .env.telegram
|
||||
```
|
||||
|
||||
### 4.2 `.env.telegram` bearbeiten
|
||||
|
||||
**Datei öffnen:** `scripts/.env.telegram`
|
||||
|
||||
```bash
|
||||
# Telegram Bot Configuration
|
||||
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
TELEGRAM_CHAT_ID=-1001234567890
|
||||
```
|
||||
|
||||
**Deine echten Werte eintragen:**
|
||||
- `TELEGRAM_BOT_TOKEN` → Token von BotFather (Schritt 1.3)
|
||||
- `TELEGRAM_CHAT_ID` → Chat-ID aus Schritt 3 (negativ!)
|
||||
|
||||
**Speichern** und schließen.
|
||||
|
||||
---
|
||||
|
||||
## 5. Dependencies installieren
|
||||
|
||||
```bash
|
||||
cd scripts
|
||||
|
||||
# package.json initialisieren (falls nicht vorhanden)
|
||||
npm init -y
|
||||
|
||||
# Telegram Bot API installieren
|
||||
npm install node-telegram-bot-api dotenv
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe:**
|
||||
```
|
||||
added 15 packages, and audited 16 packages in 2s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Test-Script ausführen
|
||||
|
||||
### 6.1 Script starten
|
||||
|
||||
```bash
|
||||
node telegram-test.js
|
||||
```
|
||||
|
||||
### 6.2 Erwartete Ausgabe (Erfolg)
|
||||
|
||||
```
|
||||
🔧 Lade Telegram-Konfiguration...
|
||||
✅ Konfiguration geladen!
|
||||
|
||||
🤖 Verbinde mit Telegram Bot...
|
||||
✅ Telegram Bot erfolgreich verbunden!
|
||||
|
||||
Bot-Details:
|
||||
Name: Werkstatt Image Uploader Bot
|
||||
Username: @werkstatt_uploader_bot
|
||||
ID: 1234567890
|
||||
|
||||
📤 Sende Test-Nachricht an Chat -1001234567890...
|
||||
✅ Nachricht erfolgreich gesendet!
|
||||
|
||||
Message-ID: 42
|
||||
```
|
||||
|
||||
### 6.3 Telegram-Gruppe prüfen
|
||||
|
||||
**In der Test-Gruppe sollte jetzt erscheinen:**
|
||||
|
||||
```
|
||||
🤖 Telegram Bot Test
|
||||
|
||||
Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot.
|
||||
|
||||
Status: ✅ Erfolgreich verbunden!
|
||||
Zeitstempel: 2025-11-29 14:23:45
|
||||
|
||||
---
|
||||
ℹ️ Dieser Bot sendet automatische Benachrichtigungen für den Image Uploader.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Troubleshooting
|
||||
|
||||
### ❌ Fehler: "Error: Unauthorized (401)"
|
||||
|
||||
**Ursache:** Bot-Token ist falsch oder ungültig
|
||||
|
||||
**Lösung:**
|
||||
1. BotFather öffnen
|
||||
2. `/token` eingeben
|
||||
3. Deinen Bot auswählen
|
||||
4. Neuen Token kopieren
|
||||
5. `.env.telegram` aktualisieren
|
||||
6. Script erneut starten
|
||||
|
||||
---
|
||||
|
||||
### ❌ Fehler: "Bad Request: chat not found"
|
||||
|
||||
**Ursache:** Chat-ID ist falsch
|
||||
|
||||
**Lösung:**
|
||||
1. Test-Gruppe öffnen
|
||||
2. Neue Nachricht senden
|
||||
3. Chat-ID erneut ermitteln (Schritt 3)
|
||||
4. `.env.telegram` aktualisieren
|
||||
5. Script erneut starten
|
||||
|
||||
---
|
||||
|
||||
### ❌ Fehler: "Error: ETELEGRAM: 403 Forbidden"
|
||||
|
||||
**Ursache:** Bot wurde aus der Gruppe entfernt oder kann nicht posten
|
||||
|
||||
**Lösung:**
|
||||
1. Test-Gruppe öffnen
|
||||
2. Prüfen, ob Bot noch Mitglied ist
|
||||
3. Falls nicht: Bot erneut hinzufügen (Schritt 2.2)
|
||||
4. Falls ja: Bot als Admin hinzufügen (Schritt 2.3)
|
||||
5. Script erneut starten
|
||||
|
||||
---
|
||||
|
||||
### ❌ Fehler: "Cannot find module 'node-telegram-bot-api'"
|
||||
|
||||
**Ursache:** Dependencies nicht installiert
|
||||
|
||||
**Lösung:**
|
||||
```bash
|
||||
cd scripts
|
||||
npm install
|
||||
node telegram-test.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Fehler: "TELEGRAM_BOT_TOKEN is not defined"
|
||||
|
||||
**Ursache:** `.env.telegram` fehlt oder nicht korrekt
|
||||
|
||||
**Lösung:**
|
||||
1. Prüfen, ob `.env.telegram` existiert: `ls -la scripts/.env.telegram`
|
||||
2. Falls nicht: Template kopieren (Schritt 4.1)
|
||||
3. Werte eintragen (Schritt 4.2)
|
||||
4. Script erneut starten
|
||||
|
||||
---
|
||||
|
||||
## 8. Erweiterte Tests
|
||||
|
||||
### Test 1: Formatierung mit Emojis
|
||||
|
||||
**Script anpassen:** `telegram-test.js`
|
||||
|
||||
```javascript
|
||||
const message = `
|
||||
📸 Neuer Upload!
|
||||
|
||||
Uploader: Max Mustermann
|
||||
Bilder: 12
|
||||
Gruppe: 2024 - Schweißkurs November
|
||||
|
||||
Workshop: ✅ Ja
|
||||
Social Media: 📘 Instagram, 🎵 TikTok
|
||||
|
||||
🔗 Zur Freigabe: https://internal.hobbyhimmel.de/moderation
|
||||
`;
|
||||
|
||||
bot.sendMessage(chatId, message);
|
||||
```
|
||||
|
||||
**Ausführen:**
|
||||
```bash
|
||||
node telegram-test.js
|
||||
```
|
||||
|
||||
**Telegram prüfen:** Emojis sollten korrekt angezeigt werden
|
||||
|
||||
---
|
||||
|
||||
### Test 2: HTML-Formatierung
|
||||
|
||||
**Script anpassen:**
|
||||
|
||||
```javascript
|
||||
const message = `
|
||||
<b>🤖 Telegram Bot Test</b>
|
||||
|
||||
<i>HTML-Formatierung funktioniert!</i>
|
||||
|
||||
<code>Status: ✅ Erfolgreich</code>
|
||||
|
||||
<a href="https://hobbyhimmel.de">Link zur Website</a>
|
||||
`;
|
||||
|
||||
bot.sendMessage(chatId, message, { parse_mode: 'HTML' });
|
||||
```
|
||||
|
||||
**Ausführen & prüfen:** Fetter Text, kursiver Text, Code, Link
|
||||
|
||||
---
|
||||
|
||||
### Test 3: Markdown-Formatierung
|
||||
|
||||
**Script anpassen:**
|
||||
|
||||
```javascript
|
||||
const message = `
|
||||
*🤖 Telegram Bot Test*
|
||||
|
||||
_Markdown-Formatierung funktioniert!_
|
||||
|
||||
\`Status: ✅ Erfolgreich\`
|
||||
|
||||
[Link zur Website](https://hobbyhimmel.de)
|
||||
`;
|
||||
|
||||
bot.sendMessage(chatId, message, { parse_mode: 'Markdown' });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Sicherheit
|
||||
|
||||
### ⚠️ Wichtig!
|
||||
|
||||
- ❌ **NIEMALS** `.env.telegram` committen!
|
||||
- ❌ **NIEMALS** Bot-Token öffentlich teilen!
|
||||
- ✅ `.env.telegram` ist in `.gitignore` eingetragen
|
||||
- ✅ Nur `.env.telegram.example` (ohne echte Tokens) committen
|
||||
|
||||
### Bot-Token kompromittiert?
|
||||
|
||||
**Falls Token versehentlich exposed:**
|
||||
|
||||
1. BotFather öffnen
|
||||
2. `/revoke` eingeben
|
||||
3. Deinen Bot auswählen
|
||||
4. **Neuen Token** kopieren
|
||||
5. `.env.telegram` aktualisieren
|
||||
6. Alle Services neu starten
|
||||
|
||||
---
|
||||
|
||||
## 10. Nächste Schritte
|
||||
|
||||
### ✅ Phase 1 abgeschlossen?
|
||||
|
||||
Checklist:
|
||||
- [x] Bot erstellt
|
||||
- [x] Test-Gruppe erstellt
|
||||
- [x] Bot zur Gruppe hinzugefügt
|
||||
- [x] Chat-ID ermittelt
|
||||
- [x] `.env.telegram` konfiguriert
|
||||
- [x] `npm install` erfolgreich
|
||||
- [x] `node telegram-test.js` läuft ohne Fehler
|
||||
- [x] Test-Nachricht in Telegram empfangen
|
||||
|
||||
### ➡️ Weiter zu Phase 2
|
||||
|
||||
**Backend-Integration:**
|
||||
1. `TelegramNotificationService.js` erstellen
|
||||
2. Service in Docker Dev Environment integrieren
|
||||
3. ENV-Variablen in Backend übertragen
|
||||
4. Unit-Tests schreiben
|
||||
|
||||
**Siehe:** `FeatureRequests/FEATURE_PLAN-telegram.md`
|
||||
|
||||
---
|
||||
|
||||
## Referenzen
|
||||
|
||||
- [Telegram Bot API Dokumentation](https://core.telegram.org/bots/api)
|
||||
- [node-telegram-bot-api (npm)](https://www.npmjs.com/package/node-telegram-bot-api)
|
||||
- [BotFather Commands](https://core.telegram.org/bots#botfather)
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
**Bei Problemen:**
|
||||
1. Troubleshooting-Sektion durchlesen (Schritt 7)
|
||||
2. Telegram Bot API Logs prüfen
|
||||
3. BotFather `/mybots` → Bot auswählen → API Token prüfen
|
||||
4. Chat-ID erneut ermitteln
|
||||
|
||||
**Erfolgreicher Test? 🎉**
|
||||
```bash
|
||||
git add scripts/
|
||||
git commit -m "feat: Add Telegram Bot standalone test (Phase 1)"
|
||||
```
|
||||
166
scripts/telegram-test.js
Normal file
166
scripts/telegram-test.js
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Telegram Bot Standalone Test Script
|
||||
*
|
||||
* Testet die grundlegende Funktionalität des Telegram Bots
|
||||
* ohne Integration in das Backend.
|
||||
*
|
||||
* Phase 1: Bot Setup & Standalone-Test
|
||||
*
|
||||
* Usage:
|
||||
* node telegram-test.js
|
||||
*
|
||||
* Prerequisites:
|
||||
* - .env.telegram mit TELEGRAM_BOT_TOKEN und TELEGRAM_CHAT_ID
|
||||
* - npm install node-telegram-bot-api dotenv
|
||||
*/
|
||||
|
||||
require('dotenv').config({ path: '.env.telegram' });
|
||||
const TelegramBot = require('node-telegram-bot-api');
|
||||
|
||||
// =============================================================================
|
||||
// Configuration
|
||||
// =============================================================================
|
||||
|
||||
const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
|
||||
const CHAT_ID = process.env.TELEGRAM_CHAT_ID;
|
||||
|
||||
// =============================================================================
|
||||
// Validation
|
||||
// =============================================================================
|
||||
|
||||
console.log('🔧 Lade Telegram-Konfiguration...');
|
||||
|
||||
if (!BOT_TOKEN) {
|
||||
console.error('❌ FEHLER: TELEGRAM_BOT_TOKEN ist nicht definiert!');
|
||||
console.error('');
|
||||
console.error('Bitte .env.telegram erstellen und Bot-Token eintragen:');
|
||||
console.error('');
|
||||
console.error(' TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz');
|
||||
console.error(' TELEGRAM_CHAT_ID=-1001234567890');
|
||||
console.error('');
|
||||
console.error('Siehe: scripts/README.telegram.md');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (!CHAT_ID) {
|
||||
console.error('❌ FEHLER: TELEGRAM_CHAT_ID ist nicht definiert!');
|
||||
console.error('');
|
||||
console.error('Bitte .env.telegram erstellen und Chat-ID eintragen:');
|
||||
console.error('');
|
||||
console.error(' TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz');
|
||||
console.error(' TELEGRAM_CHAT_ID=-1001234567890');
|
||||
console.error('');
|
||||
console.error('Chat-ID ermitteln: https://api.telegram.org/bot<TOKEN>/getUpdates');
|
||||
console.error('Siehe: scripts/README.telegram.md');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('✅ Konfiguration geladen!');
|
||||
console.log('');
|
||||
|
||||
// =============================================================================
|
||||
// Bot Initialization
|
||||
// =============================================================================
|
||||
|
||||
console.log('🤖 Verbinde mit Telegram Bot...');
|
||||
|
||||
// Create bot instance (polling disabled for one-off script)
|
||||
const bot = new TelegramBot(BOT_TOKEN, { polling: false });
|
||||
|
||||
// =============================================================================
|
||||
// Main Test Function
|
||||
// =============================================================================
|
||||
|
||||
async function runTest() {
|
||||
try {
|
||||
// Step 1: Verify bot connection
|
||||
const botInfo = await bot.getMe();
|
||||
|
||||
console.log('✅ Telegram Bot erfolgreich verbunden!');
|
||||
console.log('');
|
||||
console.log('Bot-Details:');
|
||||
console.log(` Name: ${botInfo.first_name}`);
|
||||
console.log(` Username: @${botInfo.username}`);
|
||||
console.log(` ID: ${botInfo.id}`);
|
||||
console.log('');
|
||||
|
||||
// Step 2: Prepare test message
|
||||
const timestamp = new Date().toLocaleString('de-DE', {
|
||||
year: 'numeric',
|
||||
month: '2-digit',
|
||||
day: '2-digit',
|
||||
hour: '2-digit',
|
||||
minute: '2-digit',
|
||||
second: '2-digit'
|
||||
});
|
||||
|
||||
const message = `
|
||||
🤖 Telegram Bot Test
|
||||
|
||||
Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot.
|
||||
|
||||
Status: ✅ Erfolgreich verbunden!
|
||||
Zeitstempel: ${timestamp}
|
||||
|
||||
---
|
||||
ℹ️ Dieser Bot sendet automatische Benachrichtigungen für den Image Uploader.
|
||||
`.trim();
|
||||
|
||||
// Step 3: Send test message
|
||||
console.log(`📤 Sende Test-Nachricht an Chat ${CHAT_ID}...`);
|
||||
|
||||
const sentMessage = await bot.sendMessage(CHAT_ID, message);
|
||||
|
||||
console.log('✅ Nachricht erfolgreich gesendet!');
|
||||
console.log('');
|
||||
console.log(`Message-ID: ${sentMessage.message_id}`);
|
||||
console.log('');
|
||||
console.log('🎉 Test erfolgreich abgeschlossen!');
|
||||
console.log('');
|
||||
console.log('➡️ Nächste Schritte:');
|
||||
console.log(' 1. Telegram-Gruppe öffnen und Nachricht prüfen');
|
||||
console.log(' 2. Verschiedene Nachrichtenformate testen (siehe README.telegram.md)');
|
||||
console.log(' 3. Phase 2 starten: Backend-Integration');
|
||||
|
||||
} catch (error) {
|
||||
console.error('❌ FEHLER beim Senden der Nachricht:');
|
||||
console.error('');
|
||||
|
||||
if (error.response && error.response.body) {
|
||||
const errorData = error.response.body;
|
||||
console.error(`Error Code: ${errorData.error_code}`);
|
||||
console.error(`Description: ${errorData.description}`);
|
||||
console.error('');
|
||||
|
||||
// Helpful error messages
|
||||
if (errorData.error_code === 401) {
|
||||
console.error('💡 Lösung: Bot-Token ist ungültig oder falsch.');
|
||||
console.error(' → BotFather öffnen und Token prüfen');
|
||||
console.error(' → .env.telegram aktualisieren');
|
||||
} else if (errorData.error_code === 400 && errorData.description.includes('chat not found')) {
|
||||
console.error('💡 Lösung: Chat-ID ist falsch oder ungültig.');
|
||||
console.error(' → Chat-ID erneut ermitteln: https://api.telegram.org/bot<TOKEN>/getUpdates');
|
||||
console.error(' → Neue Nachricht in Gruppe senden, dann getUpdates aufrufen');
|
||||
console.error(' → .env.telegram aktualisieren');
|
||||
} else if (errorData.error_code === 403) {
|
||||
console.error('💡 Lösung: Bot hat keine Berechtigung, in diese Gruppe zu schreiben.');
|
||||
console.error(' → Bot zur Gruppe hinzufügen');
|
||||
console.error(' → Bot als Admin hinzufügen (empfohlen)');
|
||||
}
|
||||
} else {
|
||||
console.error(error.message);
|
||||
}
|
||||
|
||||
console.error('');
|
||||
console.error('📖 Siehe Troubleshooting: scripts/README.telegram.md');
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// Execute Test
|
||||
// =============================================================================
|
||||
|
||||
runTest();
|
||||
Loading…
Reference in New Issue
Block a user