Skip to main content

Manage notification preferences

Section ID: Guide/jbkvg6uv30#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 ID: Guide/jbkvg6uv30#read-preferences

Request example: Get notification preferences · Request fields.

See Get notification preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • (root): empty object.

Response:

Response example: Get notification preferences · Response fields.

See Get notification preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • global.enabled: boolean true.
  • global.channels.inApp: boolean true.
  • global.channels.push: boolean true.
  • global.channels.email: boolean false.
  • workflows[0].workflowId: text promotional.
  • workflows[0].workflowName: text Promotional.
  • workflows[0].critical: boolean false.
  • workflows[0].tags[0]: text marketing.
  • workflows[0].channels.inApp: boolean true.
  • workflows[0].channels.push: boolean false.
  • workflows[1].workflowId: text weekly-summary.
  • workflows[1].workflowName: text Weekly Summary.
  • workflows[1].critical: boolean false.
  • workflows[1].channels.inApp: boolean true.
  • workflows[1].channels.push: boolean true.

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

2. Turn push off across ordinary notifications​

Section ID: Guide/jbkvg6uv30#update-the-global-toggles

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

Request example: Update global notification preferences · Request fields.

See Update global notification preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • channels.push: boolean 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 ID: Guide/jbkvg6uv30#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.

See Update per-workflow notification preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • workflowId: text promotional.
  • channels.push: boolean false.
  • channels.email: boolean 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 ID: Guide/jbkvg6uv30#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.

See Bulk-update per-workflow preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • entries[0].workflowId: text promotional.
  • entries[0].channels.push: boolean false.
  • entries[1].workflowId: text weekly-summary.
  • entries[1].channels.inApp: boolean true.
  • entries[1].channels.push: boolean true.

Response:

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

See Bulk-update per-workflow preferences for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • updatedCount: number 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 ID: Guide/jbkvg6uv30#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 ID: Guide/jbkvg6uv30#channel-names

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

Document ID: Guide/jbkvg6uv30