Értesítések API

Beérkezett üzenetek és kézbesítési vezérlők

Értesítések olvasása, kézbesítés hangolása, eszközök regisztrálása és beérkező levelek szabályainak alakítása

Ezek az útvonalak táplálják a bejelentkezett értesítési postafiókot, a kézbesítési beállításokat, a push-eszköz nyilvántartását, szűrőket és szabályokat, némítási hatóköröket és szálszintű műveleteket.

JWT vagy felhasználói API kulcsBeérkező levelek szűrésePush eszközökSzabályok és némítások

Hitelesítés és engedélyek

• Ezen az oldalon minden útvonal hitelesítést igényel.
• Minden a hitelesített felhasználóra vonatkozik.
• A filters és a rules párhuzamos útvonalcsaládok ugyanazon mögöttes koncepcióhoz az aktuális vezérlőfelületen.

Végpont referencia

Beérkezett üzenetek és kézbesítés

módszer	Útvonal	Cél	Kérjen vagy érdeklődjön	Auth
GET	/api/notifications	Értesítések listázása.	Lekérdezés: unreadOnly,archived,threadId,afterCursor	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/:id/read	Jelölj meg egy értesítést olvasottnak.	Elérési út: id	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/:id/unread	Egy értesítés megjelölése olvasatlanként.	Elérési út: id	JWT vagy felhasználói API kulcs
POST	/api/notifications/read-all	Minden értesítés megjelölése olvasottként.	Egyik sem	JWT vagy felhasználói API kulcs
GET	/api/notifications/catalog	Olvassa el az értesítési katalógust.	Egyik sem	JWT vagy felhasználói API kulcs
GET	/api/notifications/scopes	Olvassa el az adott típushoz rendelkezésre álló hatóköröket.	Lekérdezés: type	JWT vagy felhasználói API kulcs
GET	/api/notifications/preferences	Olvassa el a szállítási beállításokat.	Egyik sem	JWT vagy felhasználói API kulcs
PUT	/api/notifications/preferences	Cserélje ki a kézbesítési beállításokat.	Törzs: preferences	JWT vagy felhasználói API kulcs
POST	/api/notifications/devices	Regisztráljon egy push eszközt.	Törzs: platform,token,userAgent	JWT vagy felhasználói API kulcs
DELETE	/api/notifications/devices/:deviceId	Push eszköz törlése.	Elérési út: deviceId	JWT vagy felhasználói API kulcs

Szűrők és szabályok

módszer	Útvonal	Cél	Kérjen vagy érdeklődjön	Auth
GET	/api/notifications/filters	Szűrési szabályok listája.	Egyik sem	JWT vagy felhasználói API kulcs
POST	/api/notifications/filters	Hozzon létre vagy frissítsen egy szűrőt.	Törzs: a beérkező levelek szabályának hasznos terhelése	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/filters	Cserélje ki vagy rendelje újra a szűrőket.	Törzs: rules	JWT vagy felhasználói API kulcs
DELETE	/api/notifications/filters/:id	Töröljön egy szűrőt.	Elérési út: id	JWT vagy felhasználói API kulcs
GET	/api/notifications/rules	Szabályok listája.	Egyik sem	JWT vagy felhasználói API kulcs
POST	/api/notifications/rules	Hozzon létre vagy frissítsen egy szabályt.	Törzs: a beérkező levelek szabályának hasznos terhelése	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/rules	Cserélje ki vagy rendezze át a szabályokat.	Törzs: rules	JWT vagy felhasználói API kulcs
DELETE	/api/notifications/rules/:id	Töröljön egy szabályt.	Elérési út: id	JWT vagy felhasználói API kulcs

Némák és szálak

módszer	Útvonal	Cél	Kérjen vagy érdeklődjön	Auth
GET	/api/notifications/mutes	Listázza a némított hatóköröket.	Egyik sem	JWT vagy felhasználói API kulcs
POST	/api/notifications/mutes	Némítás létrehozása vagy frissítése.	Törzs: scopeType,scopeId,isMuted	JWT vagy felhasználói API kulcs
DELETE	/api/notifications/mutes/:scopeType/:scopeId	Távolítson el egy némítást.	Elérési út: scopeType,scopeId	JWT vagy felhasználói API kulcs
GET	/api/notifications/threads	Értesítési szálak listázása.	Egyik sem	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/threads/:id/mute	Egy szál némítása.	Elérési út: id	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/threads/:id/unmute	Egy szál némításának feloldása.	Elérési út: id	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/threads/:id/archive	Archiváljon egy szálat.	Elérési út: id	JWT vagy felhasználói API kulcs
PATCH	/api/notifications/threads/:id/unarchive	Egy szál archiválásának megszüntetése.	Elérési út: id	JWT vagy felhasználói API kulcs

Kérjen alakzatokat

Lista lekérdezés

ListNotificationsQueryDto

• unreadOnly: opcionális logikai érték
• archived: opcionális logikai érték
• threadId: opcionális szám
• afterCursor: opcionális karakterlánc

Preferences

UpdateNotificationPreferencesDto.preferences[]

• eventType: kötelező karakterlánc
• channels: szükséges objektumtérkép
• digest: opcionális karakterlánc
• fallbackOrder: opcionális karakterlánc tömb
• quietHours: opcionális objektum vagy null

Eszköz regisztráció

RegisterDeviceDto

• platform: kötelező web|ios|android
• token: kötelező karakterlánc
• userAgent: opcionális karakterlánc

Mode Pack és visszajelzés

PUT /api/notifications/mode-pack törzs:

• modePack: "focus_adhd" | "work_store" | "family" | null — a null törli a kiválasztást

Egy pack kiválasztása (újra) betelepíti az adott pack tulajdonában lévő beérkezőlevél-szabályok egy kis csoportját (belsőleg egy packOwned oszloppal megjelölve, így a pack váltása soha nem érinti a saját, kézzel létrehozott szabályaidat), és eltávolítja azokat a szabályokat, amelyeket az előző pack telepített. A family jelenleg nem telepít szabályokat (még nincs gyermek/csak-megtekintés szerepkör a platformon), így a kiválasztása csak a beállítást rögzíti. A mentett UserNotificationSettings sort adja vissza (userId, modePack, feedbackTuning, createdAt, updatedAt).

A GET /api/notifications/mode-pack ugyanezt az alakzatot adja vissza, vagy null-t, ha a felhasználó még soha nem állított be ilyet.

POST /api/notifications/feedback törzs:

• class: kötelező, az alábbiak egyike: critical|time_critical|coordination|operational|fyi (NotificationClass enum)
• direction: kötelező, "too_much" | "too_quiet"

A too_much egy fokozattal csendesebbé teszi az adott osztályt a jövőbeli értesítéseknél (a hold_for_gap/batch_digest irányú útválasztás felé); a too_quiet egy fokozattal hangosabbá teszi (az interrupt_now felé). A critical soha nem állítható így - a triázs motor ennél az osztálynál mindig figyelmen kívül hagyja a visszajelzés-hangolást. A frissített UserNotificationSettings sort adja vissza az új feedbackTuning térképpel (pl. { "operational": -1 }).

Szűrők és szabályok

InboxRuleDto

• id: opcionális szám
• name: kötelező karakterlánc
• scopeType: kötelező global|organisation|calendar|reservation
• scopeId: nem kötelező
• isEnabled: kötelező logikai érték
• conditions: szükséges { field, operator, value } tömb
• actions: szükséges { type, payload } tömb
• continueProcessing: opcionális logikai érték
• order: opcionális szám

UpdateInboxRulesDto.rules: szükséges InboxRuleDto tömb

Némít

ScopeMuteDto

• scopeType: kötelező organisation|calendar|reservation|resource|thread
• scopeId: kötelező karakterlánc
• isMuted: kötelező logikai érték

Példahívások

Az olvasatlan értesítések listázása

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

Frissítse a beállításokat

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"]
      }
    ]
  }'

Regisztráljon egy eszközt

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"
  }'

Hozzon létre egy némítást

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

Válasz és viselkedés megjegyzések

• A GET /api/notifications/catalog a legbiztonságosabb forrás preferencia- vagy szabályszerkesztők létrehozásához.
• A GET /api/notifications/scopes a kért értesítéstípus jelenleg érvényes hatókör-beállításait adja vissza.
• A szűrő- és szabályútvonalak egyaránt aktívak a vezérlőfelületen; kezelje őket párhuzamos belépési pontokként ugyanahhoz a modellhez.
• Az eszköztörlés és a némító törlés inkább sikeres stílusú válaszokat ad vissza, nem pedig gazdag objektumokat.

Legjobb gyakorlatok

• Használja a afterCursor-t a beérkező levelek növekményes betöltéséhez a nagy, korlátlan lista lekérése helyett.
• Szabályszerkesztőket készíthet az élő katalógusból és a hatókör végpontjaiból a kemény kódolású eseménytípusok helyett.
• Tartsa az eszköz regisztrációját idempotensen a kliensben. A háttérrendszer újra fel tud használni egy meglévő token társítást.
• Előnyben részesítse a némításokat az ideiglenes elnyomáshoz, és a szabályokat a hosszú élettartamú útválasztáshoz vagy archiváláshoz.
• A szálműveleteket külön tegye közzé a felhasználói felületen. A szál némítása/archiválása eltér a hatókörszintű némítási beállításoktól.