Kommunikation & Alarm-Pipeline¶

Uebersicht¶

Die Comm-API stellt direkte REST-Endpoints fuer Benachrichtigungen bereit: Telefonanrufe, Telegram-Nachrichten, Voice-Messages und Multi-Channel-Dispatch.

Zusaetzlich kann ueber die Workflow-Engine ein vollstaendiger Alarm-Workflow (IMAP → Subject-Parsing → Multi-Channel-Dispatch) getriggert werden.

Authentifizierung¶

Alle Comm-Endpoints akzeptieren zwei Auth-Methoden:

Methode	Header	Scope
Service-Token	`x-service-token: <token>`	Platform (voller Zugriff)
Bearer Token	`Authorization: Bearer <jwt>`	User (Permission: `workflows.manage`)

Service-Tokens sind fuer Maschine-zu-Maschine Kommunikation gedacht (Monitoring-Scripte, Cronjobs, andere Dienste).

Direkte APIs¶

Telefonanruf (TTS)¶

POST /api/v1/comm/call

Startet einen ausgehenden Anruf via FreeSwitch ESL mit TTS-Sprachnachricht.

Request Body:

{
  "target": "+491772340318",
  "text": "Achtung: Server nicht erreichbar!",
  "tts_provider": "qwen3",
  "tts_voice": "Dylan",
  "gateway": "1und1",
  "pause_ms": 4000,
  "repeat": 2
}

Feld	Typ	Default	Beschreibung
`target`	string	erforderlich	Telefonnummer (E.164 Format)
`text`	string	erforderlich	TTS-Text fuer die Sprachnachricht
`tts_provider`	string	`qwen3`	TTS Provider: `piper`, `qwen3`, `elevenlabs`
`tts_voice`	string	Provider-Default	Stimme (z.B. `Dylan`, `thorsten`)
`gateway`	string	`1und1`	SIP-Gateway
`pause_ms`	int	`4000`	Pause nach Abnehmen in ms
`repeat`	int	`2`	Nachricht X-mal abspielen

Beispiel:

curl -X POST https://platform.xynap.tech/api/v1/comm/call \
  -H "x-service-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"+491772340318","text":"Server-Alarm!","tts_provider":"qwen3"}'

Telegram Text-Nachricht¶

POST /api/v1/comm/telegram

Request Body:

{
  "chat_id": "207215057",
  "text": "Server-Alarm: CPU bei 100%",
  "severity": "CRITICAL"
}

Feld	Typ	Default	Beschreibung
`chat_id`	string	erforderlich	Telegram Chat-ID
`text`	string	erforderlich	Nachrichtentext
`severity`	string	`""`	Severity-Prefix (ALERT, CRITICAL, WARNING, INFO)

Telegram Voice-Nachricht¶

POST /api/v1/comm/telegram/voice

Generiert Audio via TTS Gateway und sendet es als Telegram Voice-Nachricht.

Request Body:

{
  "chat_id": "207215057",
  "text": "Server-Alarm: CPU Auslastung kritisch!",
  "caption": "Alarm: Server XY",
  "tts_provider": "qwen3",
  "tts_voice": "Dylan"
}

Feld	Typ	Default	Beschreibung
`chat_id`	string	erforderlich	Telegram Chat-ID
`text`	string	erforderlich	TTS-Text fuer die Voice-Nachricht
`caption`	string	`""`	Caption unter der Voice-Nachricht
`tts_provider`	string	`qwen3`	TTS Provider
`tts_voice`	string	Provider-Default	TTS Stimme

Multi-Channel Benachrichtigung¶

POST /api/v1/comm/notify

Sendet Benachrichtigungen ueber mehrere Kanaele parallel.

Request Body:

{
  "channels": [
    {"channel": "call", "target": "+491772340318"},
    {"channel": "telegram_voice", "target": "207215057"},
    {"channel": "telegram", "target": "207215057"}
  ],
  "text": "Server XY ist nicht erreichbar!",
  "severity": "CRITICAL",
  "tts_provider": "qwen3",
  "tts_voice": "Dylan"
}

Unterstuetzte Kanaele:

Kanal	Beschreibung
`call`	Telefonanruf mit TTS-Sprachnachricht
`telegram`	Telegram Text-Nachricht
`telegram_voice`	Telegram Voice-Nachricht (TTS)
`webhook`	HTTP POST an URL
`sms`	SMS (Placeholder)

Health-Check¶

GET /api/v1/comm/health

Prueft alle Komponenten der Comm-Pipeline: Redis, TTS Gateway, FreeSwitch ESL, Telegram Bot.

Response:

{
  "status": "ok",
  "components": {
    "redis": {"status": "ok", "latency_ms": 1.2},
    "tts": {"status": "ok", "provider": "qwen3"},
    "freeswitch": {"status": "ok"},
    "telegram": {"status": "ok"}
  }
}

Heartbeat¶

POST /api/v1/comm/heartbeat

Sendet eine Test-Nachricht via Telegram und fuehrt anschliessend einen Health-Check durch. Erfordert Bearer Token (User-Auth).

Workflow-Trigger (E-Mail Alarm)¶

Fuer vollstaendige Alarm-Workflows mit Subject-Parsing, Spam-Protection und Retry-Logik:

POST /api/v1/workflows/trigger

{
  "event_type": "email.alarm.received",
  "payload": {
    "email_subject": "CRITICAL:CALL+491772340318;TELEGRAM_VOICE+207215057;RETRY:3x5m",
    "email_body": "Server XY ist nicht erreichbar seit 10 Minuten.",
    "email_from": "monitoring@xynap.tech"
  }
}

Subject-Format¶

SEVERITY:CHANNEL+TARGET[;CHANNEL+TARGET;...][;RETRY:NxMm]

Element	Beschreibung	Beispiel
Severity	Alarm-Stufe	`ALERT`, `CRITICAL`, `WARNING`, `INFO`
CALL	Telefonanruf	`CALL+491772340318`
TELEGRAM	Telegram Text	`TELEGRAM+207215057`
TELEGRAM_VOICE	Telegram Voice	`TELEGRAM_VOICE+207215057`
WEBHOOK	HTTP POST	`WEBHOOK+https://hooks.example.com/alert`
SMS	SMS	`SMS+491772340318`
RETRY	Retry bei Fehler	`RETRY:3x5m` (3 Versuche, 5 Min Pause)

Workflow-Ablauf¶

1. email.parse_subject   → Severity + Actions extrahieren, Spam-Check
2. comm.dispatch_actions → Alle Kanaele parallel/sequentiell bedienen
3. comm.log_result       → Ergebnis in DB + Redis loggen

Spam Protection¶

Der Parser prueft erlaubte Absender und Domains (konfigurierbar im Workflow):

config = {
    "allowed_senders": ["monitoring@xynap.tech"],
    "allowed_domains": ["isn-systems.com", "xynap.tech"],
}

Deduplication¶

Redis-basiert: Identische Alarme (gleicher Subject + Sender) werden innerhalb des Cooldown-Zeitraums (default 600s) dedupliziert.

Call-Locking¶

Globale Anruf-Sperre via Redis: Maximal ein aktiver Alarm-Call gleichzeitig. Nachfolgende Calls warten max 90s, danach force-send.

TTS Provider¶

Provider	Qualitaet	Latenz	GPU	Beschreibung
`piper`	Gut	~100ms	Nein	Lokal, schnell, deutsch (thorsten)
`qwen3`	Sehr gut	~2-5s	Ja (CUDA)	Natuerliche Stimme (Dylan, u.a.)
`elevenlabs`	Premium	~1-3s	Nein	Cloud-API, viele Stimmen

TTS Gateway: http://127.0.0.1:5200/synthesize — Unterstuetzt Caching, Format-Konvertierung (WAV, OGG, MP3) und Voice-Aliases.

CLI: notify-ctl¶

# Direkte Anrufe/Nachrichten
notify-ctl call +491772340318 "Server down!"
notify-ctl telegram 207215057 "Alarm-Text"
notify-ctl voice 207215057 "Voice-Nachricht"
notify-ctl notify "call:+491772340318,telegram_voice:207215057" "Alarm!"

# Workflow-Trigger
notify-ctl trigger "ALERT:CALL+491772340318;TELEGRAM_VOICE+207215057" "Text"

# Mail-Verwaltung
notify-ctl mail list-domains
notify-ctl mail list-accounts 1
notify-ctl mail create-account 1 neuer-user

# Status
notify-ctl status

Config: /etc/xynap/notify-ctl.conf

API_URL=http://172.23.0.9:8099
SERVICE_TOKEN=<service-token>

IMAP Alarm-Poller¶

Der bridge-email Service pollt ein IMAP-Postfach und triggert automatisch Alarm-Workflows bei neuen E-Mails:

IMAP (mailbot@xynap.tech) → bridge-email → POST /api/v1/workflows/trigger
                                          → email.alarm.received Event
                                          → EmailAlarmWorkflow

Config: /etc/xynap/comm-hub/bridges/email.env