# Telegram Watchdog — Design Document

## 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:**
```json
{
  "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()

```js
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)