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:

{
  "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)

curl "https://api.telegram.org/bot<DEIN_BOT_TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

---

4. Environment-Datei erstellen

4.1 Template kopieren

cd scripts
cp .env.telegram.example .env.telegram

4.2 .env.telegram bearbeiten

Datei öffnen: scripts/.env.telegram

# 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

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

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:

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

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:

node telegram-test.js

Telegram prüfen: Emojis sollten korrekt angezeigt werden

---

Test 2: HTML-Formatierung

Script anpassen:

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:

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:

• Bot erstellt
• Test-Gruppe erstellt
• Bot zur Gruppe hinzugefügt
• Chat-ID ermittelt
• .env.telegram konfiguriert
• npm install erfolgreich
• node telegram-test.js läuft ohne Fehler
• 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
• node-telegram-bot-api (npm)
• BotFather Commands

---

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? 🎉

git add scripts/
git commit -m "feat: Add Telegram Bot standalone test (Phase 1)"