Skip to main content

Manage notification preferences

Section: DOC-CP-notifications-preferences#manage-notification-preferences.

Build a settings screen where a user can turn off push across the app while keeping in-app updates, then make a narrower choice for one notification type. Start by reading saved preferences, render inherited values distinctly, send only changed choices, and read back the result before treating a failed or partial save as complete.

Show which choices apply app-wide and which apply to one notification type. Explain any critical-message policy separately; see preference inheritance.

1. Load saved choices before rendering settings​

Section: DOC-CP-notifications-preferences#read-preferences.

Request example: Get notification preferences · Request fields.

{}

Response:

Response example: Get notification preferences · Response fields.

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

Keep inherited and explicit choices distinct in the controls; follow the presence rules.

2. Turn push off across ordinary notifications​

Section: DOC-CP-notifications-preferences#update-the-global-toggles.

Send only the choices the user changed, following the update contract:

Request example: Update global notification preferences · Request fields.

{
  "channels": {"push": false}
}

Response: {} on success. Reload preferences to confirm the saved selections.

Confirm the saved ordinary-notification preference and leave other choices intact. Critical-message handling is a separate policy.

Variant: change one kind of notification​

Section: DOC-CP-notifications-preferences#update-one-workflow.

Offer this choice when a user wants fewer messages of one kind without changing all notifications. Use the workflow ID returned by the loaded settings, preserve its untouched channels, and leave broader channel preferences in force.

Request example: Update per-workflow notification preferences · Request fields.

{
  "workflowId": "promotional",
  "channels": {"push": false, "email": false}
}

Response: {} on success. Reload preferences to confirm the saved selections.

Use the workflow-specific update contract for this row.

3. Save several edited rows together​

Section: DOC-CP-notifications-preferences#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.

Request example: Bulk-update per-workflow preferences · Request fields.

{
  "entries": [
    {
      "workflowId": "promotional",
      "channels": {"push": false}
    },
    {
      "workflowId": "weekly-summary",
      "channels": {"inApp": true, "push": true}
    }
  ]
}

Response:

Response example: Bulk-update per-workflow preferences · Response fields.

{
  "updatedCount": 2
}

Compare the saved rows with the intended changes and follow partial-update handling before showing success.

4. Confirm the saved choices and recover partial failure​

Section: DOC-CP-notifications-preferences#save-and-recover-changes.

Check the returned count after updating multiple workflows. If only some changed, refetch the affected preferences, show the incomplete result and retry only the choices still needed. If the UI updates optimistically, restore or refetch failed rows and prevent an older response from overwriting a newer user choice. Disabling a preference cannot recall a notification already accepted for delivery.

Reference: map channel values to settings controls​

Section: DOC-CP-notifications-preferences#channel-names.

Map each control to the preference channel keys; channel registration and activity filters use their own documented spellings.

Document ID: DOC-CP-notifications-preferences. Section identities and revisions.