Communication & Alarm pipeline¶

Overview¶

The Comm-API provides direct REST endpoints for notifications: Telephone calls, telegram messages, voice messages and multi-channel dispatches.

In addition, the workflow engine can provide a full alert workflow (IMAP → Subject-Parsing → Multi-Channel Dispatch) are triggered.

Authentication¶

All Comm Endpoints accept two Auth methods :

Method	Header	Scope
Service tokens	`x-service-token: <token>`	Platform (full access)
Bearer Token	`Authorization: Bearer <jwt>`	User (Permission:`workflows.manage`)

Service tokens are intended for machine-to-machine communication (monitoring scripts, cronjobs, other services).

Direct APIs¶

Phone call (TTS)¶

POST /api/v1/comm/call

Starts an outgoing call via FreeSwitch ESL with TTS voice message.

Request Body:

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

Field	Type	Default	Description
`target`	string	required	Phone number (E.164 format)
`text`	string	required	TTS text for the voice message
`tts_provider`	string	`qwen3`	TTS Provider:`piper`,`qwen3`,`elevenlabs`
`tts_voice`	string	Provider default	Voice (e.g.`Dylan`,`thorsten`)
`gateway`	string	`1und1`	SIP gateway
`pause_ms`	int	`4000`	Break after take-off in ms
`repeat`	int	`2`	Message X-mal

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 Message¶

POST /api/v1/comm/telegram

Request Body:

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

Field	Type	Default	Description
`chat_id`	string	required	Telegram Chat ID
`text`	string	required	Message
`severity`	string	`""`	Severity Prefix (ALERT, CRITICAL, WARNING, INFO)

Telegram Voice Message¶

POST /api/v1/comm/telegram/voice

Generates audio via TTS Gateway and sends it as a Telegram Voice message.

Request Body:

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

Field	Type	Default	Description
`chat_id`	string	required	Telegram Chat ID
`text`	string	required	TTS text for the voice message
`caption`	string	`""`	Caption under the voice message
`tts_provider`	string	`qwen3`	TTS Provider
`tts_voice`	string	Provider default	TTS voice

Multi-channel notification¶

POST /api/v1/comm/notify

Sends notifications via several canals in 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:

Channel	Description
`call`	Phone call with TTS voice message
`telegram`	Telegram Text Message
`telegram_voice`	Telegram Voice Message (TTS)
`webhook`	HTTP POST to URL
`sms`	SMS (Placeholder)

Health check¶

GET /api/v1/comm/health

Prueft all components of 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

Sends a test message via Telegram and then passes a health check. Requires Bearer Token (User-Auth).

Workflow trigger (e-mail alarm)¶

Full alert workflows with Subject-Parsing, Spam-Protection and 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	Description	Example
Severity	Alarm level	`ALERT`,`CRITICAL`,`WARNING`,`INFO`
CALL	Phone call	`CALL+491772340318`
TELEGRAM	Telegram Text	`TELEGRAM+207215057`
TELEGRAM VOICE	Telegram Voice	`TELEGRAM_VOICE+207215057`
WEBHOOK	HTTP POST	`WEBHOOK+https://hooks.example.com/alert`
TEXT	TEXT	`SMS+491772340318`
RETRY	Retry in error	`RETRY:3x5m`(3 tests, 5 min break)

Workflow run¶

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¶

The Parser prueft allows senders and domains (configurable in the workflow):

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

Deduplication¶

Redis-based: Identical alarms (same Subject + Transmitter) become within of the cooldown period (default 600s) deduplicated.

Call-locking¶

Global call spin via Redis: Maximum an active alarm call simultaneously. Following calls wait max 90s, then force-send.

TTS Provider¶

Provider	Quality	Latin	GPU	Description
`piper`	Good	~100ms	No	Local, fast, German (thorsten)
`qwen3`	Very good	~2-5s	Yes (CUDA)	Natuary voice (Dylan, etc.)
`elevenlabs`	Premium	~1-3s	No	Cloud API, many voices

TTS Gateway:http://127.0.0.1:5200/synthesize— Supported caching, Format conversion (WAV, OGG, MP3) and 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 Police¶

The bridge email service pollts an IMAP mailbox and automatically triggers Alarm workflows for new emails:

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

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