Project-Image-Uploader/scripts/README.telegram.md

# 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)"
```