> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preferences

> Learn how subscriber preferences work in WorldVisa, how workflow-level and channel-level preferences interact, and how to expose settings to end users.

WorldVisa provides a way to store subscriber preferences. This allows subscribers, your users, to specify and manage their preferences and customize their notifications experience.

**Levels of preferences:**

* Workflow channel preferences
* Subscriber channel preferences per workflow
* Subscriber global preferences

## Workflow channel preferences

Each workflow has its own channel preferences. By default, all channel preferences are enabled. If disabled, the subscriber will not receive notifications for that channel step.

Steps to manage workflow channel preferences:

**1. Go to the Workflows page**

Open the Workflows page in the WorldVisa dashboard.

**2. Select a workflow**

Click the workflow you want to manage channel preferences for

**3. Open channel preferences**

A node-based editor will appear. On the right side of the editor, click the `Configure channel preferences` option

**4. Enable or disable all channels**

Use the channel toggles to choose the workflow’s default delivery channels.

**5. Configure step preferences**

You will be able to change the preferences for only those steps which are present in the workflow. Non existing channel steps will be disabled.

**6. Mark as critical (optional)**

The `Mark as critical` toggle will make this workflow critical. Read more about [critical workflows](#critical-workflows)

> [!NOTE]
>
> If a workflow has only `in-app` and `email` steps, then it will have only `in-app` and `email` preferences.

![Workflow channel preferences](https://mintcdn.com/wv-enterprise/l3bkwl1N_3mOn9aW/images/developers/concepts/preferences/workflow-channel-preferences.png?fit=max\&auto=format\&n=l3bkwl1N_3mOn9aW\&q=85\&s=ed967747c33330fda2d4f770ad64c026)

### Critical workflows

In some cases, you don't want the subscriber to be able to unsubscribe from mandatory notifications such as Account Verification, Password Reset, etc...

In those cases, you can mark a workflow as `critical` in the workflow channel preferences. Critical workflows are not displayed in subscriber preferences, so subscribers cannot change preferences for that workflow.

## Subscriber global preferences

Subscribers can set global channel preferences, which apply across every workflow. For instance, if there are 10 workflows and a subscriber wants to disable SMS notifications for all of them, they can do so with global preferences instead of changing each workflow.

Global preferences act as the subscriber's baseline. If the same subscriber later sets a preference for one specific workflow, that more specific choice wins for that workflow. See [Priority of preferences](#priority-of-preferences).

![Preferences](https://mintcdn.com/wv-enterprise/l3bkwl1N_3mOn9aW/images/developers/inbox/preferences@2x.png?fit=max\&auto=format\&n=l3bkwl1N_3mOn9aW\&q=85\&s=ad953c9da11ac56b4a84f1c811c443d6)

## Subscriber channel preferences per workflow

For each workflow, each subscriber has their own channel preferences. Subscribers can manage these preferences from the `<Inbox />`  Preferences view.

![Subscriber channel preferences](https://mintcdn.com/wv-enterprise/l3bkwl1N_3mOn9aW/images/developers/concepts/preferences/subscriber-workflow-preferences.png?fit=max\&auto=format\&n=l3bkwl1N_3mOn9aW\&q=85\&s=4565c03120aa5b1629d22809bfcf3dbe)

> [!NOTE]
>
> Inbox displays only channels present in the current workflow.

## Priority of preferences

WorldVisa resolves preferences per channel. It layers each type of preference on top of the previous one, from the most general to the most specific, and **the most specific layer that defines a channel wins**:

1. Workflow channel preferences configured in the dashboard
2. Subscriber global preferences
3. Subscriber channel preferences per workflow

So a subscriber's per-workflow choice takes precedence over their global choice, and both take precedence over the workflow defaults.

The one exception is [critical workflows](#critical-workflows). When a workflow is marked as critical, both subscriber layers are discarded and the workflow channel preferences decide on their own.

```mermaid theme={null}
flowchart TD
    startNode([Should this channel send?]) --> isCritical{Workflow marked as critical?}
    isCritical -->|Yes| useWorkflow[Use the workflow channel preference]
    isCritical -->|No| hasWorkflowPref{Subscriber set a preference for this workflow?}
    hasWorkflowPref -->|Yes| useSubscriberWorkflow[Use the subscriber preference for this workflow]
    hasWorkflowPref -->|No| hasGlobalPref{Subscriber set a global preference for this channel?}
    hasGlobalPref -->|Yes| useSubscriberGlobal[Use the subscriber global preference]
    hasGlobalPref -->|No| useWorkflow
    useWorkflow --> resolved{Resolved value enabled?}
    useSubscriberWorkflow --> resolved
    useSubscriberGlobal --> resolved
    resolved -->|Yes| sendAllowed[Send notification]
    resolved -->|No| blocked[Do not send]
```

Examples:

1. If the `email` channel is enabled in workflow channel preferences but the subscriber disabled `email` globally, they will not receive email notifications for this workflow.
2. If the subscriber disabled `email` globally but enabled `email` for this specific workflow, they will receive email notifications for this workflow. The per-workflow preference is more specific than the global one.
3. If the `in-app` channel is enabled in workflow channel preferences and the workflow is marked as critical, subscribers cannot change their preferences and will always receive in-app notifications.

Preferences are stored per environment. When the Inbox is initialized with a [tenant context](https://docs.worldvisagroup.com/developers/concepts/tenants.md), they are stored for that subscriber and tenant together, so the same person can opt in for one tenant and opt out for another.

> [!NOTE]
>
> Only channels that exist as active steps in the workflow are considered. A channel that the workflow does not use is never resolved, whatever the subscriber set for it globally.

## Subscriber preferences APIs

Retrieve preferences with `GET /v1/subscribers/{subscriberId}/preferences`, or global settings with `GET /v1/subscribers/{subscriberId}/preferences/global`.

Update settings with `PATCH /v1/subscribers/{subscriberId}/preferences`. Include `workflowId` in the request to change that workflow’s preferences; leave it out to change global preferences.


## Related topics

- [Preferences](https://docs.worldvisagroup.com/developers/inbox/configuration/preferences.md)
- [Localization](https://docs.worldvisagroup.com/developers/inbox/advanced-features/localization.md)
- [How do workflows work in WorldVisa?](https://docs.worldvisagroup.com/developers/concepts/workflows.md)
- [How do subscribers work in WorldVisa?](https://docs.worldvisagroup.com/developers/concepts/subscribers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.