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

# User preferences

> Let each user decide which notifications they receive and on which channels. Preferences link one user to one notification type and drive who gets notified.

Preferences let each of your users decide which notifications they receive and on which channels. A preference is the link between **one user** and **one notification type**: it records whether that type is enabled for them and which channels to use.

When a notification is sent, Archie looks at the recipient's preference for that type:

* **No preference row yet?** The type's **Default subscribed** setting decides whether they receive it.
* **Preference exists and is enabled with at least one channel?** They receive it on those channels.
* **Preference exists but is disabled?** They are skipped — *unless* the type is **Mandatory**, which always reaches everyone.

<Note>
  Preferences are scoped per environment, like everything else in the Notifications module.
</Note>

## Anatomy of a preference

| Field                                      | Meaning                                                                                                              |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **User** (`userId`)                        | The user this preference belongs to.                                                                                 |
| **Notification type** (`notificationType`) | The type being configured.                                                                                           |
| **Enabled** (`isEnabled`)                  | Whether the user wants this notification at all.                                                                     |
| **Channels** (`channels`)                  | Which channels to deliver on (e.g., `["in_app", "email"]`). An enabled preference with no channels delivers nothing. |
| **Email / Phone / WhatsApp**               | Optional per-user contact overrides for the relevant channels.                                                       |

A user has at most **one** preference per type — the pair *(user, type)* is unique.

## Configure from the Archie web app

Most teams expose preferences inside their own application's "Notification settings" screen, but you can also manage them directly:

<Steps>
  <Step title="Open the Preferences tab">
    Navigate to **App Services → Notifications** and open the **Preferences** tab.
  </Step>

  <Step title="Find a user">
    Search for a user, then click **+ Add Preference** (or edit an existing row).
  </Step>

  <Step title="Configure the preference">
    Choose the **Notification type**, toggle **Enabled**, and select the **Channels**.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## Configure through the GraphQL API

Preferences are a standard table, available through the auto-generated [GraphQL](/docs/features/backend/graphql-api-explorer/overview) operations on your project endpoint (`https://archie-core.services.archie.com/graphql`) with the `X-Project-Id`, `X-Environment`, and `Authorization` headers.

### Set (or update) a user's preference

The most common pattern is "create it if missing, update it if present." You can do that with a single upsert-style call keyed on *(user, type)*:

```graphql theme={null}
mutation SavePreference {
  createArchieUserNotificationPreferences(
    input: {
      userId: "2685ec12-a4c7-491d-a155-d0b09190993b"
      notificationType: "b2c8…"        # the notification type id
      isEnabled: true
      channels: ["in_app", "email"]
    }
  ) {
    id
    userId
    isEnabled
    channels
  }
}
```

To change channels or turn a type off later:

```graphql theme={null}
mutation DisableType {
  updateArchieUserNotificationPreferences(
    id: "pref-id…"
    input: { isEnabled: false }
  ) {
    id
    isEnabled
  }
}
```

### Read a user's preferences

```graphql theme={null}
query MyPreferences {
  archieUserNotificationPreferences(
    filter: { userId: { equals: "2685ec12-a4c7-491d-a155-d0b09190993b" } }
  ) {
    items {
      id
      isEnabled
      channels
      notificationType {
        eventKey
        name
      }
    }
  }
}
```

<Note>
  **Soft-deleted records.** List queries exclude soft-deleted rows by default. To include preferences that have been soft-deleted, pass the `withDeleted: true` argument on the list query (e.g., `archieUserNotificationPreferences(withDeleted: true) { items { id } }`). Omit it — or set it to `false` — to return only active rows.
</Note>

### Build a "notification settings" screen

A typical settings page combines the two tables:

1. Read the catalog of **active, user-configurable** types (`archieNotificationTypes` where `isActive = true` and `canBeDisabled = true`).
2. Read the user's existing **preferences**.
3. For each type, show a toggle and channel pickers, pre-filled from the preference (or from the type's defaults when the user has no row yet).
4. On save, create or update the matching preference.

<Note>
  **Mandatory types** (`isMandatory = true`) should be shown as read-only — the user always receives them, so don't offer an off switch.
</Note>

## Next step

With your catalog and preferences in place, you're ready to [send notifications](/docs/features/backend/app-services/notifications/sending-notifications).