---
title: "Persönliche Benachrichtigungseinstellungen"
description: "Wie Incident Management dich erreicht: Kanäle, Benachrichtigungsregeln je Dringlichkeit, Kanäle je Schweregrad, Telefonbestätigung, Test-Benachrichtigungen und dein Benachrichtigungsprotokoll."
---

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

## Begriffe

- **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.

## Authentifizierung

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 lesen

`GET /api/im/notification-settings`

### Beispiel (cURL)

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

### Antwort (Response)

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

`PATCH /api/im/notification-settings`

### Request Body

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `phoneNumber` | string oder null | Nein | E.164-Nummer, oder `null` zum Entfernen. Eine neue Nummer ist unbestätigt, bis sie bestätigt wird; ein offener Bestätigungscode verfällt. Vorhandene `sms`/`voice`-Regeln bleiben bestehen, werden aber übersprungen, solange die Nummer unbestätigt ist. |
| `channels` | object | Nein | Kanalschalter (`push`, `sms`, `voice`, `email` → boolean), werden in die gespeicherten eingemischt. |

### Beispiel (cURL)

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

### Antwort (Response)

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

## Kanäle in einem Schritt setzen

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

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `channels` | object | Ja | Mindestens einer von `push`, `sms`, `voice`, `email`, jeweils `{ "enabled": boolean, "delayMinutes": 0..1440 }`. |

### Beispiel (cURL)

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

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

`PUT /api/im/notification-settings/severity`

Ersetzt den gespeicherten Filter vollständig.

### Request Body

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `severityChannels` | object | Ja | Schlüssel `sev1` bis `sev4`, jeweils ein Objekt aus `push`/`sms`/`voice`/`email` → boolean. Nicht genannte Schweregrade und Kanäle sind erlaubt. `{}` erlaubt alles. |

### Beispiel (cURL)

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

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

## Regel anlegen

`POST /api/im/notification-settings/rules`

### Request Body

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `urgency` | string | Ja | `high` oder `low`. |
| `delayMinutes` | integer | Ja | 0 bis 1440. |
| `channel` | string | Ja | `push`, `sms`, `voice` oder `email`. `sms` und `voice` brauchen eine bestätigte Telefonnummer. |

### Beispiel (cURL)

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

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

## Regel löschen

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

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

## Telefonnummer bestätigen

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

```json
{ "sent": true }
```

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

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `code` | string | Ja | Der 6-stellige Code. |

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

```json
{ "phoneVerified": true }
```

## Test-Benachrichtigung senden

`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](/de/api/incident-management/setup#test-alarm-senden).

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

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

| Parameter | Typ | Pflicht | Beschreibung |
|-----------|-----|---------|--------------|
| `limit` | integer | Nein | 1 bis 100, Standard 50. |
| `before` | integer | Nein | Liefert Einträge, die älter als diese Eintrags-ID sind; nimm `nextBefore` der vorigen Seite. |

### Antwort (Response)

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

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