Persönliche Benachrichtigungseinstellungen

GET /api/im/notification-settings · PATCH /api/im/notification-settings · PUT /api/im/notification-settings/channels · PUT /api/im/notification-settings/severity · POST /api/im/notification-settings/rules · DELETE /api/im/notification-settings/rules/:id · POST /api/im/notification-settings/verify-phone · POST /api/im/notification-settings/verify-phone-confirm · POST /api/im/notification-settings/test · GET /api/im/notification-settings/logs

Wenn eine Eskalation dich alarmiert, entscheiden diese Einstellungen, wie du erreicht wirst. Sie gehören nur dir: Jeder Endpunkt liest und schreibt die Einstellungen der aufrufenden Person, die von jemand anderem lassen sich nicht ändern. Beim ersten Zugriff werden deine Einstellungen angelegt.

BegriffeAnkerlink kopieren

• Kanäle: push (Mobile App), sms, voice und email.
• Regeln bilden deine persönliche Benachrichtigungskette je Dringlichkeit (high oder low): „nach delayMinutes über channel benachrichtigen“. Eine Verzögerung von 0 benachrichtigt sofort; erlaubt sind 0 bis 1440 Minuten. Dieselbe Kombination aus Dringlichkeit, Verzögerung und Kanal gibt es höchstens einmal.
• Schweregrad-Filter (severityChannels): je Schweregrad des Incidents (sev1 bis sev4), welche Kanäle genutzt werden dürfen. Er wird sparsam gespeichert: Ein nicht genannter Schweregrad oder Kanal ist erlaubt. {"sev4": {"sms": false, "voice": false}} hält Incidents niedriger Schwere von deinem Telefon fern und ändert sonst nichts.
• Telefon: sms und voice brauchen eine bestätigte Telefonnummer im E.164-Format (+ und 7 bis 15 Ziffern, z. B. +491701234567). Eine geänderte Nummer muss neu bestätigt werden.

AuthentifizierungAnkerlink kopieren

Jede IM-berechtigte Rolle (admin, editor, responder) mit einer Benutzersitzung. Incident Management muss für die Organisation aktiviert sein. Persönliche Einstellungen gehören einer Person: Ein organisationsweiter API-Token erhält 403 (imAccessDenied), beim Protokoll 403 (imUserSessionRequired).

Einstellungen lesenAnkerlink kopieren

GET /api/im/notification-settings

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/notification-settings" \
  -b "$SESSION_COOKIE" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

{
  "id": 31,
  "phoneNumber": "+491701234567",
  "phoneVerified": true,
  "channels": { "push": true, "sms": true, "email": true },
  "severityChannels": { "sev4": { "sms": false, "voice": false } },
  "rules": [
    { "id": 201, "urgency": "high", "delayMinutes": 0, "channel": "push" },
    { "id": 202, "urgency": "high", "delayMinutes": 5, "channel": "sms" },
    { "id": 203, "urgency": "low", "delayMinutes": 0, "channel": "email" }
  ]
}

rules ist nach Dringlichkeit, dann Verzögerung sortiert.

Telefonnummer oder Kanalschalter ändernAnkerlink kopieren

PATCH /api/im/notification-settings

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/notification-settings" \
  -b "$SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+491701234567"}'

Antwort (Response)Ankerlink kopieren

{
  "id": 31,
  "phoneNumber": "+491701234567",
  "phoneVerified": false,
  "channels": { "push": true, "email": true }
}

Kanäle in einem Schritt setzenAnkerlink kopieren

PUT /api/im/notification-settings/channels

Die einfache Form der Regelkette: je Kanal an oder aus mit einer Verzögerung, gültig für beide Dringlichkeiten. Für jeden genannten Kanal werden seine bisherigen Regeln ersetzt; nicht genannte Kanäle bleiben, wie sie sind.

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PUT "$BASE_URL/api/im/notification-settings/channels" \
  -b "$SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"channels":{"push":{"enabled":true,"delayMinutes":0},"sms":{"enabled":true,"delayMinutes":5}}}'

Antwort (Response)Ankerlink kopieren

{
  "channels": { "push": true, "sms": true },
  "rules": [
    { "id": 210, "urgency": "high", "delayMinutes": 0, "channel": "push" },
    { "id": 211, "urgency": "high", "delayMinutes": 5, "channel": "sms" },
    { "id": 212, "urgency": "low", "delayMinutes": 0, "channel": "push" },
    { "id": 213, "urgency": "low", "delayMinutes": 5, "channel": "sms" }
  ]
}

Schweregrad-Filter setzenAnkerlink kopieren

PUT /api/im/notification-settings/severity

Ersetzt den gespeicherten Filter vollständig.

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PUT "$BASE_URL/api/im/notification-settings/severity" \
  -b "$SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"severityChannels":{"sev4":{"sms":false,"voice":false}}}'

Antwort (Response)Ankerlink kopieren

{
  "severityChannels": { "sev4": { "sms": false, "voice": false } }
}

Regel anlegenAnkerlink kopieren

POST /api/im/notification-settings/rules

Request BodyAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/notification-settings/rules" \
  -b "$SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"urgency":"high","delayMinutes":10,"channel":"voice"}'

Antwort (Response)Ankerlink kopieren

{ "id": 214, "urgency": "high", "delayMinutes": 10, "channel": "voice" }

Regel löschenAnkerlink kopieren

DELETE /api/im/notification-settings/rules/:id

Löscht eine deiner Regeln. Liefert { "success": true }.

Telefonnummer bestätigenAnkerlink kopieren

POST /api/im/notification-settings/verify-phone schickt einen 6-stelligen Code per SMS an die gespeicherte Nummer. Der Code gilt 10 Minuten und erlaubt 5 Versuche. Pro Stunde lassen sich höchstens 3 Codes anfordern.

{ "sent": true }

POST /api/im/notification-settings/verify-phone-confirm bestätigt ihn:

curl -X POST "$BASE_URL/api/im/notification-settings/verify-phone-confirm" \
  -b "$SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"code":"482913"}'

{ "phoneVerified": true }

Test-Benachrichtigung sendenAnkerlink kopieren

POST /api/im/notification-settings/test

Schickt auf jedem Kanal eine Testnachricht, so wie dich ein sev1-Incident nach deinem Schweregrad-Filter erreichen würde. Es wird kein Incident angelegt. Höchstens 5 pro Stunde, gemeinsam mit dem Test-Alarm der Einrichtung.

{
  "results": [
    { "channel": "email", "ok": true },
    { "channel": "sms", "ok": false, "error": "phone_not_verified" },
    { "channel": "push", "ok": true },
    { "channel": "voice", "ok": false, "error": "not_available_yet" }
  ]
}

Werte von error: disabled_by_settings (durch deinen Schweregrad-Filter ausgeschlossen), phone_not_verified, no_email_on_account, not_available_yet (für Sprachanrufe gibt es noch keinen Test) oder die Fehlermeldung des Anbieters.

Dein BenachrichtigungsprotokollAnkerlink kopieren

GET /api/im/notification-settings/logs

Jede Benachrichtigung, die Incident Management für dich geplant, gesendet, übersprungen, abgebrochen oder nicht zustellen konnte, neueste zuerst.

Query-ParameterAnkerlink kopieren

Antwort (Response)Ankerlink kopieren

{
  "entries": [
    {
      "id": 99812,
      "at": "2026-10-10T07:12:03.000Z",
      "kind": "notification_sent",
      "channel": "sms",
      "reason": null,
      "error": null,
      "provider": "seven",
      "tier": 1,
      "repeat": 0,
      "delayMinutes": 5,
      "urgency": "high",
      "incident": { "id": "1834", "title": "API 5xx rate above 5 %", "severity": "sev2", "status": "acknowledged" }
    }
  ],
  "hasMore": true,
  "nextBefore": 99812
}

kind ist einer von notification_scheduled, notification_sent, notification_failed, notification_cancelled, notification_skipped; reason und error erklären Übersprungenes und Fehlschläge.

Häufige FehlerAnkerlink kopieren

• 400 Bad Request (invalidRequestBody) bei ungültigem Body oder Query: unbekannter Kanal oder unbekannte Dringlichkeit, Verzögerung außerhalb von 0 bis 1440, fehlerhaftes severityChannels, ein Code, der nicht aus 6 Ziffern besteht, limit/before außerhalb des Bereichs
• 400 Bad Request (invalidPhoneNumber) wenn phoneNumber nicht im E.164-Format ist
• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (imAccessDenied) wenn keine IM-berechtigte Rolle vorliegt oder mit einem organisationsweiten API-Token aufgerufen wird
• 403 Forbidden (imUserSessionRequired) wenn das Protokoll mit einem organisationsweiten API-Token gelesen wird
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 404 Not Found (imNotificationRuleNotFound) wenn die Regel nicht existiert oder nicht dir gehört
• 409 Conflict (imNotificationRuleExists) wenn dieselbe Regel aus Dringlichkeit, Verzögerung und Kanal schon existiert
• 422 Unprocessable Entity (imPhoneNotVerified) beim Einschalten von sms/voice ohne bestätigte Nummer
• 422 Unprocessable Entity (imPhoneNotSet) beim Anfordern eines Codes ohne gespeicherte Nummer
• 422 Unprocessable Entity (imPhoneVerifyCodeInvalid, imPhoneVerifyCodeExpired, imPhoneVerifyTooManyAttempts) wenn der Code falsch, älter als 10 Minuten oder zu oft versucht ist
• 429 Too Many Requests (imPhoneVerifyRateLimited) nach 3 Codes in einer Stunde; (imTestNotificationRateLimited) nach 5 Test-Benachrichtigungen in einer Stunde. Beide liefern retryAfterSeconds.
• 502 Bad Gateway (imPhoneVerifySendFailed) wenn der SMS-Anbieter die Code-Nachricht abgelehnt hat