Benachrichtigungen API

Posteingangs- und Versandkontrollen

Benachrichtigungen lesen, Zustellung optimieren, Geräte registrieren und Posteingangsregeln festlegen

Diese Routen steuern den Posteingang für angemeldete Benachrichtigungen, die Zustellungseinstellungen, die Push-Geräte-Registrierung usw. Filter und Regeln, Stummschaltungsbereiche und Aktionen auf Thread-Ebene.

JWT oder Benutzer API SchlüsselPosteingangsfilterungPush-GeräteRegeln und Stummschaltungen

Authentifizierung und Berechtigungen

• Alle Routen auf dieser Seite erfordern eine Authentifizierung.
• Alles ist auf den authentifizierten Benutzer beschränkt.
• filters und rules sind parallele Routenfamilien für dasselbe zugrunde liegende Konzept in der aktuellen Controller-Oberfläche.

Endpunktreferenz

Posteingang und Lieferung

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth
GET	/api/notifications	Benachrichtigungen auflisten.	Abfrage: unreadOnly,archived,threadId,afterCursor	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/:id/read	Markieren Sie eine Benachrichtigung als gelesen.	Pfad: id	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/:id/unread	Markieren Sie eine Benachrichtigung als ungelesen.	Pfad: id	JWT oder Benutzerschlüssel API
POST	/api/notifications/read-all	Alle Benachrichtigungen als gelesen markieren.	Keine	JWT oder Benutzerschlüssel API
GET	/api/notifications/catalog	Lesen Sie den Benachrichtigungskatalog.	Keine	JWT oder Benutzerschlüssel API
GET	/api/notifications/scopes	Verfügbare Bereiche für einen Typ lesen.	Abfrage: type	JWT oder Benutzerschlüssel API
GET	/api/notifications/preferences	Lieferpräferenzen lesen.	Keine	JWT oder Benutzerschlüssel API
PUT	/api/notifications/preferences	Ersetzen Sie die Liefereinstellungen.	Körper: preferences	JWT oder Benutzerschlüssel API
POST	/api/notifications/devices	Registrieren Sie ein Push-Gerät.	Körper: platform,token,userAgent	JWT oder Benutzerschlüssel API
DELETE	/api/notifications/devices/:deviceId	Löschen Sie ein Push-Gerät.	Pfad: deviceId	JWT oder Benutzerschlüssel API

Filter und Regeln

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth
GET	/api/notifications/filters	Filterregeln auflisten.	Keine	JWT oder Benutzerschlüssel API
POST	/api/notifications/filters	Erstellen oder aktualisieren Sie einen Filter.	Text: Nutzlast der Posteingangsregel	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/filters	Filter austauschen oder neu anordnen.	Körper: rules	JWT oder Benutzerschlüssel API
DELETE	/api/notifications/filters/:id	Einen Filter löschen.	Pfad: id	JWT oder Benutzerschlüssel API
GET	/api/notifications/rules	Regeln auflisten.	Keine	JWT oder Benutzerschlüssel API
POST	/api/notifications/rules	Erstellen oder aktualisieren Sie eine Regel.	Text: Nutzlast der Posteingangsregel	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/rules	Regeln ersetzen oder neu anordnen.	Körper: rules	JWT oder Benutzerschlüssel API
DELETE	/api/notifications/rules/:id	Löschen Sie eine Regel.	Pfad: id	JWT oder Benutzerschlüssel API

Stummschaltungen und Threads

Methode	Pfad	Zweck	Anfrage oder Anfrage	Auth
GET	/api/notifications/mutes	Stummgeschaltete Bereiche auflisten.	Keine	JWT oder Benutzerschlüssel API
POST	/api/notifications/mutes	Erstellen oder aktualisieren Sie eine Stummschaltung.	Körper: scopeType,scopeId,isMuted	JWT oder Benutzerschlüssel API
DELETE	/api/notifications/mutes/:scopeType/:scopeId	Entfernen Sie eine Stummschaltung.	Pfad: scopeType,scopeId	JWT oder Benutzerschlüssel API
GET	/api/notifications/threads	Benachrichtigungsthreads auflisten.	Keine	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/threads/:id/mute	Schalten Sie einen Thread stumm.	Pfad: id	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/threads/:id/unmute	Stummschaltung eines Threads aufheben.	Pfad: id	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/threads/:id/archive	Archiviere einen Thread.	Pfad: id	JWT oder Benutzerschlüssel API
PATCH	/api/notifications/threads/:id/unarchive	Einen Thread aus dem Archiv entfernen.	Pfad: id	JWT oder Benutzerschlüssel API

Fordern Sie Formen an

Listenabfrage

ListNotificationsQueryDto

• unreadOnly: optionaler boolescher Wert
• archived: optionaler boolescher Wert
• threadId: optionale Nummer
• afterCursor: optionale Zeichenfolge

Präferenzen

UpdateNotificationPreferencesDto.preferences[]

• eventType: erforderliche Zeichenfolge
• channels: erforderliche Objektzuordnung
• digest: optionale Zeichenfolge
• fallbackOrder: optionales String-Array
• quietHours: optionales Objekt oder null

Geräteregistrierung

RegisterDeviceDto

• platform: erforderlich web|ios|android
• token: erforderliche Zeichenfolge
• userAgent: optionale Zeichenfolge

Mode Pack und Feedback

PUT /api/notifications/mode-pack Body:

• modePack: "focus_adhd" | "work_store" | "family" | null — null löscht die Auswahl

Die Auswahl eines Pakets (re-)seedet einen kleinen Satz globaler Posteingangsregeln, die diesem Paket gehören (intern über eine packOwned-Spalte gekennzeichnet, sodass ein Paketwechsel niemals deine eigenen, handangelegten Regeln berührt), und entfernt die Regeln, die das vorherige Paket gesät hatte. family sät derzeit keine Regeln (es existiert noch keine Kind-/Nur-Ansicht-Rolle auf der Plattform), sodass die Auswahl nur die Präferenz speichert. Gibt die gespeicherte UserNotificationSettings-Zeile zurück (userId, modePack, feedbackTuning, createdAt, updatedAt).

GET /api/notifications/mode-pack gibt dieselbe Struktur zurück, oder null, wenn der Benutzer noch nie eines festgelegt hat.

POST /api/notifications/feedback Body:

• class: erforderlich, eines von critical|time_critical|coordination|operational|fyi (NotificationClass-Enum)
• direction: erforderlich, "too_much" | "too_quiet"

too_much macht diese Klasse für zukünftige Benachrichtigungen eine Stufe leiser (in Richtung hold_for_gap/batch_digest-Routing); too_quiet macht sie eine Stufe lauter (in Richtung interrupt_now). critical lässt sich auf diese Weise nie anpassen - die Triage-Engine ignoriert die Feedback-Abstimmung für diese Klasse immer. Gibt die aktualisierte UserNotificationSettings-Zeile mit der neuen feedbackTuning-Zuordnung zurück (z. B. { "operational": -1 }).

Filter und Regeln

InboxRuleDto

• id: optionale Nummer
• name: erforderliche Zeichenfolge
• scopeType: erforderlich global|organisation|calendar|reservation
• scopeId: optional
• isEnabled: erforderlicher boolescher Wert
• conditions: erforderliches Array von { field, operator, value }
• actions: erforderliches Array von { type, payload }
• continueProcessing: optionaler boolescher Wert
• order: optionale Nummer

UpdateInboxRulesDto.rules: erforderliches Array von InboxRuleDto

Stummschaltung

ScopeMuteDto

• scopeType: erforderlich organisation|calendar|reservation|resource|thread
• scopeId: erforderliche Zeichenfolge
• isMuted: erforderlicher boolescher Wert

Beispielanrufe

Ungelesene Benachrichtigungen auflisten

curl "$PRIMECAL_API/api/notifications?unreadOnly=true" \
  -H "Authorization: Bearer $TOKEN"

Aktualisieren Sie die Einstellungen

curl -X PUT "$PRIMECAL_API/api/notifications/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      {
        "eventType": "event.reminder",
        "channels": {
          "inapp": true,
          "email": false,
          "webpush": true
        },
        "digest": "immediate",
        "fallbackOrder": ["webpush"]
      }
    ]
  }'

Registrieren Sie ein Gerät

curl -X POST "$PRIMECAL_API/api/notifications/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "token": "push-token-example",
    "userAgent": "Chrome 135"
  }'

Erstellen Sie eine Stummschaltung

curl -X POST "$PRIMECAL_API/api/notifications/mutes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopeType": "calendar",
    "scopeId": "12",
    "isMuted": true
  }'

Hinweise zu Reaktion und Verhalten

• GET /api/notifications/catalog ist die sicherste Quelle zum Erstellen von Präferenz- oder Regeleditoren.
• GET /api/notifications/scopes gibt die aktuell gültigen Bereichsoptionen für den angeforderten Benachrichtigungstyp zurück.
• Filter- und Regelrouten sind beide in der Controller-Oberfläche aktiv; Behandeln Sie sie als parallele Einstiegspunkte für dasselbe Modell.
• Das Löschen von Geräten und das Stummschalten des Löschens geben Antworten im Erfolgsstil statt umfangreicher Objekte zurück.

Best Practices

• Verwenden Sie afterCursor für das inkrementelle Laden des Posteingangs, anstatt eine große, unbegrenzte Liste abzurufen.
• Erstellen Sie Regeleditoren aus dem Live-Katalog und den Bereichsendpunkten, anstatt Ereignistypen fest zu codieren.
• Halten Sie die Geräteregistrierung im Client idempotent. Das Backend kann eine vorhandene Token-Zuordnung wiederverwenden.
• Bevorzugen Sie Stummschaltungen zur vorübergehenden Unterdrückung und Regeln für langlebiges Routing- oder Archivverhalten.
• Thread-Aktionen separat in der Benutzeroberfläche verfügbar machen. Thread-Stummschaltung/-Archivierung ist ein anderes Konzept als Stummschaltungseinstellungen auf Bereichsebene.