Skip to main content

Preferences

Preferences are a two-level structure: a global set of channel toggles that applies to every workflow, and a per-workflow override for the ones the user has opinions about. A channel fires only if both levels allow it.

Critical workflows — password resets, security alerts — are exempt: they are delivered regardless of preference, and are marked critical: true so you can render them as non-negotiable rather than as a toggle that silently does nothing.

Read Preferences​

POST /api/v1/notifications/get-preferences
{}

Response:

{
  "global": {
    "enabled": true,
    "channels": {
      "inApp": true,
      "push": true,
      "email": false
    }
  },
  "workflows": [
    {
      "workflowId": "promotional",
      "workflowName": "Promotional",
      "critical": false,
      "tags": ["marketing"],
      "channels": {"inApp": true, "push": false}
    },
    {
      "workflowId": "weekly-summary",
      "workflowName": "Weekly Summary",
      "critical": false,
      "channels": {"inApp": true, "push": true}
    }
  ]
}

global.enabled is the master switch — setting it false suppresses every non-critical notification whatever the individual channels say. Channels that are off are omitted rather than sent as false, so read them with a default.

Update the Global Toggles​

Applies to all workflows at once. Omitted channels are left unchanged, so this is a patch, not a replace — send only what the user actually changed.

POST /api/v1/notifications/update-global-preference
{
  "channels": {"push": false}
}

Response: empty body on success.

That call turns push off everywhere and leaves in-app, email, SMS and chat exactly as they were.

Update One Workflow​

POST /api/v1/notifications/update-workflow-preference
{
  "workflowId": "promotional",
  "channels": {"push": false, "email": false}
}

Response: empty body on success.

The same omit-to-keep rule applies. workflowId is required — there is no "apply globally" mode on this endpoint; use update-global-preference for that.

Update Many Workflows at Once​

A preferences screen usually lets the user flip several rows before hitting save. Send them in one call rather than one request per row — up to 100 workflows.

POST /api/v1/notifications/bulk-update-preferences
{
  "entries": [
    {
      "workflowId": "promotional",
      "channels": {"push": false}
    },
    {
      "workflowId": "weekly-summary",
      "channels": {"inApp": true, "push": true}
    }
  ]
}

Response:

{
  "updatedCount": 2
}

Check updatedCount against the number of entries you sent: a workflow ID that does not exist is skipped rather than failing the batch.

Channel Names​

The toggle keys are inApp, push, email, sms and chat. These are not the same tokens as the CHANNEL_* enum returned by get-registered-channels, nor the lowercase in_app names used by the activity log filter.