---
title: "Benachrichtigungen einer Person"
description: "Organisations-Admins lesen und setzen die Benachrichtigungseinstellungen einer Person: Telefonnummer, Kanäle und die ganze Benachrichtigungskette."
---

`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](/de/api/incident-management/notification-settings) 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.

## Authentifizierung

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 lesen

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

Legt die Einstellungen beim ersten Zugriff an, ausgehend von der [Standard-Benachrichtigung](/de/api/incident-management/notification-template), genau wie wenn die Person sie öffnet.

### Beispiel (cURL)

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

### Antwort (Response)

```json
{
  "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 setzen

`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 Body

| Feld | Typ | Pflicht | Beschreibung |
|-------|------|----------|-------------|
| `rules` | array | Ja | Die ganze Kette, höchstens 64 Schritte. Jeder Schritt `{ "urgency": "high" oder "low", "delayMinutes": 0..1440, "channel": "push", "sms", "voice" oder "email" }`. Jede Kombination aus Dringlichkeit, Verzögerung und Kanal höchstens einmal. Eine leere Liste entfernt alle Regeln. |
| `channels` | object | Nein | Die vier Kanalschalter (`push`, `sms`, `voice`, `email` → boolean). Fehlt das Feld, ist ein Kanal genau dann an, wenn `rules` einen Schritt dafür hat. Andere Schalter der Person (Schicht-Erinnerungen) bleiben erhalten. |
| `phoneNumber` | string oder null | Nein | E.164-Nummer, z. B. `+491701234567`. Fehlt das Feld: unverändert. `null` entfernt sie. Eine andere Nummer ist unbestätigt, bis die Person sie bestätigt; ein offener Bestätigungscode verfällt. |

Unbekannte Felder werden abgewiesen.

### Beispiel (cURL)

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

`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 Fehler

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