Benachrichtigungen einer Person

GET /api/im/users/:userId/notification-settings · PUT /api/im/users/:userId/notification-settings

Ein Organisations-Admin richtet ein, wie eine Person alarmiert wird, zum Beispiel beim Einarbeiten einer neuen Bereitschaft, damit die Person das nicht selbst tun muss. Es sind dieselben Einstellungen, die die Person unter Persönliche Benachrichtigungen sieht und ändert. Es gilt der letzte Schreibzugriff: Die Person kann danach alles ändern, und ein Admin kann es jederzeit wieder setzen. Die Person sieht auf ihrer Benachrichtigungsseite den Hinweis „Von (Admin) geändert am (Datum)“.

sms- und voice-Schritte werden auch gespeichert, solange die Telefonnummer nicht bestätigt ist. Sie warten: Jede Alarmierung bis dahin steht im Protokoll als übersprungen (Grund unverified), und die Person wird bei der nächsten Anmeldung gebeten, die Nummer zu bestätigen. An eine Nummer, die niemand bestätigt hat, geht nichts.

AuthentifizierungAnkerlink kopieren

Erfordert die Rolle admin der Organisation, mit Sitzung oder organisationsweitem API-Token (der Token arbeitet mit der Rolle der Person, die ihn erstellt hat). Kundengebundene Tokens und Kunden-Logins werden abgewiesen. Incident Management muss für die Organisation aktiviert sein.

Die Zielperson muss zu deiner Organisation gehören, aktiv sein und eine IM-fähige Rolle haben (admin, editor oder responder).

Einstellungen einer Person lesenAnkerlink kopieren

GET /api/im/users/:userId/notification-settings

Legt die Einstellungen beim ersten Zugriff an, ausgehend von der Standard-Benachrichtigung, genau wie wenn die Person sie öffnet.

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

{
  "userId": "usr_8f2c",
  "id": 31,
  "phoneNumber": "+491701234567",
  "phoneVerified": false,
  "channels": { "push": true, "sms": true, "voice": false, "email": true },
  "severityChannels": {},
  "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" }
  ],
  "lastAdminChangeAt": "2026-10-28T09:12:00.000Z",
  "lastAdminChangeBy": { "id": "usr_admin", "name": "Ada Admin" }
}

phoneVerified: false mit sms/voice-Regeln heißt: Diese Schritte warten, bis die Person die Nummer bestätigt. Der Schweregrad-Filter (severityChannels) wird angezeigt, aber hier nicht gesetzt; er bleibt die Entscheidung der Person.

Einstellungen einer Person setzenAnkerlink kopieren

PUT /api/im/users/:userId/notification-settings

Ersetzt die ganze Benachrichtigungskette der Person durch rules. Regeln, die nicht in der Liste stehen, werden gelöscht. Eine Anfrage, die nichts ändert, schreibt nichts und setzt lastAdminChangeAt nicht neu.

Request BodyAnkerlink kopieren

Unbekannte Felder werden abgewiesen.

Beispiel (cURL)Ankerlink kopieren

curl -X PUT "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+491701234567","rules":[{"urgency":"high","delayMinutes":0,"channel":"push"},{"urgency":"high","delayMinutes":5,"channel":"sms"},{"urgency":"low","delayMinutes":0,"channel":"email"}]}'

Antwort (Response)Ankerlink kopieren

200 OK: die Einstellungen nach dem Schreiben, gleiche Form wie die GET-Antwort.

Jede Änderung steht im Audit-Protokoll, mit Admin, Person und jedem Feld von altem zu neuem Wert; Telefonnummern erscheinen dort maskiert.

Häufige FehlerAnkerlink kopieren

• 400 Bad Request (invalidRequestBody) bei ungültigem Body: unbekanntes Feld, unbekannter Kanal oder Dringlichkeit, Verzögerung außerhalb 0 bis 1440, mehr als 64 Schritte, dieselbe Kombination zweimal
• 400 Bad Request (invalidPhoneNumber), wenn phoneNumber nicht im E.164-Format ist
• 400 Bad Request (imUserNotEligible), wenn die Person inaktiv ist oder keine IM-fähige Rolle hat
• 401 Unauthorized ohne Anmeldung
• 403 Forbidden (forbidden), wenn du kein admin der Organisation bist
• 403 Forbidden (imAccessDenied) für Kunden-Logins und kundengebundene Tokens
• 403 Forbidden (imNotEnabled), wenn Incident Management für die Organisation nicht aktiviert ist
• 404 Not Found (userNotFound), wenn die Person nicht existiert oder zu einer anderen Organisation gehört