dienst_echo_whatsappgroep/docs/superpowers/specs/2026-07-12-telegram-watchdog-design.md

Telegram Watchdog — Design Document

⚠️ Poort-wijziging: De telegram-bot is tijdens implementatie verhuisd van poort 3003 naar poort 3004 (juli 2026). Alle referenties naar 3003 in dit document zijn historisch en niet meer actueel. De correcte poort is 3004. Zie .env.example voor de actuele configuratie.

Doel

Een apart Telegram bot proces dat de admin waarschuwt wanneer de WhatsApp API (wwebjs-api) of de dienst-bot zelf niet bereikbaar is. Dit is het enige communicatiekanaal dat overblijft als WhatsApp uitvalt.

Architectuur

                   ┌──────────────────┐
                   │   dienst-bot     │  Node.js (nextcloud:3002)
                   │  (Express)       │
                   └──────┬───────────┘
                          │  POST /notify (alleen bij falen WhatsApp)
                          │
                   ┌──────▼───────────┐
                   │  telegram-bot    │  Node.js (nextcloud:3003)
                   │  (Express)       │
                   │                  │
                   │ ─── health check │  dienst-bot /health (elke 5min)
                   │ ─── health check │  wwebjs-api /session/status (elke 5min)
                   │ ─── Telegram API │  verstuur notificaties naar admin
                   └──────────────────┘

Twee processen

• dienst-bot (bestaand, ongewijzigd behalve notifyAdmin): stuurt bij fouten eerst WhatsApp, als dat faalt → Telegram via POST /notify
• telegram-bot (nieuw): ontvangt notificaties van dienst-bot, voert zelfstandig health checks uit, stuurt Telegram berichten

Geen nieuwe npm packages

Zowel dienst-bot als telegram-bot gebruiken alleen axios en dotenv — beide al in gebruik.

telegram-bot — specificatie

Endpoints

Endpoint	Doel
POST /notify	Ontvangt notificaties van dienst-bot (alleen als WhatsApp faalde)
GET /health	Health check voor systemd

POST /notify body:

{
  "text": "Kan wwebjs-api niet bereiken na 3 pogingen (ECONNREFUSED)"
}

Health checks (periodiek)

Elke 5 minuten worden beide endpoints gecheckt:

1. GET http://localhost:3002/health — dienst-bot
2. GET http://192.168.5.252:3001/session/status/EdGpt — wwebjs-api

Statusovergangen triggeren een notificatie:

• down → up: "✅ dienst-bot is weer online"
• up → down: "❌ dienst-bot niet bereikbaar (ECONNREFUSED)"

Notificaties bij opstart

Bij het opstarten stuurt telegram-bot direct een bericht: "✅ Telegram watchdog online — gezondheidschecks aktief"

.env variabelen (telegram-bot)

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234
TELEGRAM_ADMIN_CHAT_ID=123456789
TELEGRAM_BOT_PORT=3003
DIENST_BOT_HEALTH_URL=http://localhost:3002/health
WWEBJS_API_SESSION_URL=http://192.168.5.252:3001/session/status/EdGpt
HEALTH_CHECK_INTERVAL_MS=300000

Wijzigingen aan dienst-bot

whatsappApi.js — notifyAdmin()

async function notifyAdmin(errorText) {
  // WhatsApp eerst (als de API werkt)
  try {
    await sendTextMessage(adminNumber, `[dienst-bot fout] ${errorText}`)
  } catch (err) {
    // WhatsApp faalt (API down) → Telegram backup
    await notifyTelegram(errorText)
  }
}

async function notifyTelegram(text) {
  const url = process.env.TELEGRAM_BOT_URL
  if (!url) return
  try {
    await axios.post(`${url}/notify`, { text }, { timeout: 5000 })
  } catch (err) {
    console.error('Telegram notification failed:', err.message)
  }
}

Nieuwe .env variabele (dienst-bot)

TELEGRAM_BOT_URL=http://localhost:3003

Systemd service

Bestand: /etc/systemd/system/telegram-bot.service

• Working directory: /home/aiaiaiaiagent/whatsapp-scripts/dienst_echo_whatsappgroep
• ExecStart: /usr/bin/node src/telegramBot.js
• User: aiaiaiaiagent
• Depends: dienst-bot.service (After= dienst-bot.service)
• Restart: always

Bestanden in de repo

Bestand	Doel
src/telegramBot.js	Telegram watchdog process (Express server)
.env.example	Nieuwe TELEGRAM_* variabelen toevoegen
docs/superpowers/specs/2026-07-12-telegram-watchdog-design.md	Dit document

Geen wijzigingen aan package.json — beide processen gebruiken dezelfde dependencies.

Error handling

• telegram-bot faalt: dienst-bot logt error, verder geen impact op WhatsApp verkeer
• dienst-bot faalt: telegram-bot detecteert via health check en stuurt notificatie
• telegram-bot zelf fault: systemd restart (Restart=always)
• Telegram API timeout: loggen en negeren (geen retry nodig)