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

# Preferences

Novu provides a way to store user preferences in the subscribers data model.
This allows subscribers to specify and manage their preferences, without your intervention. Customizing preferences has become the standard expected behavior for people and Novu can take the technical burden of managing preferences off of you.

**Novu allows several levels of preferences:**

* Workflow level channel preferences
* Subscriber level channel preferences
* Global level channel preferences

## Workflow level channel preferences

When creating a new workflow on the Web platform, you can specify default preferences for the subscribers in channel settings. They will be used unless the subscriber overrides them by his own custom preference.

This will allow you to create sensible defaults but still provide the user with the ability to override them. Template level preference can be managed in channel settings. All channels are `ON` unless specified otherwise.

`Workflow Settings > Channels`

<img style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/novu-v2-docs/iBMuKOgzYB_2VB7w/images/manage-subscribers/workflow-level-channel-preferences.png?fit=max&auto=format&n=iBMuKOgzYB_2VB7w&q=85&s=b6ed5a862a7ea832627b1bb0e710add8" width="2670" height="1404" data-path="images/manage-subscribers/workflow-level-channel-preferences.png" />

## Subscriber level channel preferences

Our notification center component will show a user the available preferences, user will be able to modify on the channel level. Critical workflows will be excluded from the list. Click on cog (setting) icon on notification center component to open subscriber channel preferences page.

<img style={{ borderRadius: "0.5rem" }} src="https://mintcdn.com/novu-v2-docs/iBMuKOgzYB_2VB7w/images/manage-subscribers/user-preference.png?fit=max&auto=format&n=iBMuKOgzYB_2VB7w&q=85&s=39d5a7633e96686dde2f9154d3f3cc6b" width="460" height="707" data-path="images/manage-subscribers/user-preference.png" />

<Note>
  Only channels with a matched step will be returned from the API in
  notification center preference page. In case no channel content was found, the
  API will return an empty array.
</Note>

## Global level channel preferences

<Info>Since v0.20.0</Info>

Subscribers can set global channel preferences, which override individual settings. For instance, if there are 10 workflows, and a subscriber wants to disable SMS notifications for all of them, they can do so with a single global preference.

### Get subscriber global preference

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_API_KEY>');

    await novu.subscribers.getGlobalPreference("subscriberId" );
    ```
  </Tab>
</Tabs>

[Get subscriber's global preference API](/api-reference/subscribers/get-subscriber-global-preferences)

### Update subscriber global preference

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    import { Novu } from '@novu/node';

    const novu = new Novu('<NOVU_API_KEY>');

    // enable in-app channel and disable email channel
    await novu.subscribers.updateGlobalPreference("subscriberId", {
      enabled: true,
      preferences: [{
        type: "in_app"
        enabled: true
      }, {
        type: "email"
        enabled: false
      }]
    });
    ```
  </Tab>
</Tabs>

[Update subscriber's global preference API](/api-reference/subscribers/update-subscriber-global-preference)

<Note>Global subscriber preference can be updated and accessed using API and SDK only. Currently we have not added support of global subscriber preference in UI.</Note>

## Exclude workflows from preferences (critical workflow)

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 turn off the toggle `Users will be able to manage subscriptions` in channel settings. Workflow will become `critical`, once this toggle is turned `OFF`. By default, every workflow is `non-critical` and subscribers can manage channel preferences irrespective of workflow-level channel preferences. Critical workflow will not show on the subscriber preferences page.

## Get subscriber preferences

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    import { Novu } from "@novu/node";

    const novu = new Novu("<NOVU_API_KEY>");

    // 111 is subscriberId
    await novu.subscribers.getPreference("111");
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use Novu\SDK\Novu;

    $novu = new Novu('<NOVU_API_KEY>');

    // 111 is subscriberId
    $novu->getSubscriberPreferences('111')->toArray();
    ```
  </Tab>
</Tabs>

## Get subscriber preference by level

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    import { Novu, PreferenceLevelEnum } from '@novu/node';

    const novu = new Novu('<NOVU_API_KEY>');
    // Get global level preference
    await novu.subscribers.getPreferenceByLevel("subscriberId", PreferenceLevelEnum.GLOBAL)

    // Get template level preference
    await novu.subscribers.getPreferenceByLevel("subscriberId", PreferenceLevelEnum.TEMPLATE);
    ```
  </Tab>
</Tabs>

## Update subscriber preference for a workflow

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    import { Novu, ChannelTypeEnum } from "@novu/node";

    const novu = new Novu("<NOVU_API_KEY>");

    // enable in_app channel
    await novu.subscribers.updatePreference("subscriberId", "workflowIdentifier", {
      enabled: true,
      channel: { type: ChannelTypeEnum.IN_APP, enabled: true },
    });

    // enable email channel
    await novu.subscribers.updatePreference("subscriberId", "workflowIdentifier", {
      enabled: true,
      channel: { type: ChannelTypeEnum.EMAIL, enabled: true },
    });
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    use Novu\SDK\Novu;

    $novu = new Novu('<NOVU_API_KEY>');

    // enable in_app channel
    $novu->updateSubscriberPreference('subscriberId', 'workflowIdentfier', [
        'enabled' => true
        'channel' => [
          'type' => 'in_app',
          'enabled' => true
        ]
    ]);

    // enable email channel
    $novu->updateSubscriberPreference('subscriberId', 'workflowIdentfier', [
        'enabled' => true
        'channel' => [
          'type' => 'email',
          'enabled' => true
        ]
    ]);
    ```
  </Tab>
</Tabs>

## Order of priority of preferences

1. if `Users will be able to manage subscriptions` toggle is turned off i.e workflow is critical, this will override workflow level and subscriber level preferences and notification will always be sent.
2. if workflow is non critical and subscriber has `false` value set for `enabled` field in preference then all other channels will become inactive even if they have `true` state.
3. if workflow is non critical and subscriber has `true` value set for `enabled` field in preference then notification will be filtered based on subscriber channel preference.
4. Workflow level channel preferences will be applied to all subscribers by default unless subscriber overrides them.

`Example`

1. For `First Workflow`, `critical` is false, `enabled` is true, in\_app, email, push channels are true and sms, chat channels are false. As per above order of priority of preferences, notification will be filtered as per the subscriber preferences. The subscriber will receive in-app, email and push notifications, but not receive sms and chat notifications.

2. For `Second Workflow`, `critical` is false, `enabled` is false, all channels are true. As per above order of priority of preferences, subscriber will not receive any type of notification because all channels become disabled due to false value of `enabled` field.

3. For `Third Workflow`. `critical` is true, `enabled` is false, email, chat channels are false and the other three channels are true. As per above order of priority of preferences, subscriber will receive all type of notifications as this workflow is `critical`.

<Tabs>
  <Tab title="First Workflow">
    ```json theme={null}
    {
      "template": {
        "_id": "firstWorkflowIdentifier",
        "name": "First Workflow",
        "critical": false
      },
      "preference": {
        "enabled": true,
        "channels": {
          "in_app": true,
          "email": true,
          "sms": false,
          "push": true,
          "chat": false
        }
      }
    }
    ```
  </Tab>

  <Tab title="Second Workflow">
    ```json theme={null}
    {
      "template": {
        "_id": "secondWorkflowIdentifier",
        "name": "Second Workflow",
        "critical": false
      },
      "preference": {
        "enabled": false,
        "channels": {
          "in_app": true,
          "email": true,
          "sms": true,
          "push": true,
          "chat": true
        }
      }
    }
    ```
  </Tab>

  <Tab title="Third Workflow">
    ```json theme={null}
    {
      "template": {
        "_id": "thirdWorkflowIdentifier",
        "name": "Third Workflow",
        "critical": true
      },
      "preference": {
        "enabled": false,
        "channels": {
          "in_app": true,
          "email": false,
          "sms": true,
          "push": true,
          "chat": false
        }
      }
    }
    ```
  </Tab>
</Tabs>

## API

<CardGroup cols={3}>
  <Card title="Get subscriber preferences API" icon="plug" color="#ea5a0c" href="/api-reference/subscribers/get-subscriber-preferences" />

  <Card title="Update subscriber preference for a workflow API" icon="plug" color="#0285c7" href="/api-reference/subscribers/update-subscriber-preference" />

  <Card title="Update workflow API" icon="plug" color="#16a34a" href="/api-reference/workflows/update-workflow" />
</CardGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How to change enabled field from UI?">
    This field can only be changed using API.
  </Accordion>

  <Accordion title="What preferences are applied to a subscriber when we create a new workflow?">
    In the case of a new workflow, the subscriber will inherit all preferences
    from the workflow\.However, after subsequent preference updates, the
    subscriber's preferences will not inherit workflow-level preferences.
  </Accordion>

  <Accordion title="How to disable a workflow for a single subscriber?">
    You can turn off all workflow's channels for a subscriber using [subscriber preference](/subscribers/preferences#subscriber-level-channel-preferences). If all channels are off, then the subscriber will not receive any message from any channel step and hence workflow is disabled for that subscriber
  </Accordion>
</AccordionGroup>