With [Liveblocks Notifications](/notifications), you can already create an
in-app notifications inbox inside your product. When users miss any in-app
notifications, Liveblocks enables sending notifications on alternate channels,
such as email, Slack, Microsoft Teams, Web Push.

Today, we’re introducing new configuration options that enable building
notification settings panels, allowing each of your end users to individually
choose which channels they should receive notifications on. With our latest
update, it’s just a couple of lines of code to get started.

<MarketingCallout>
  To add an inbox to your app, create a Liveblocks account and get started for
  free.
</MarketingCallout>

## What does it enable?

With this new update, you’ll be able to create a user notifications panel in
your application. Users will be able to choose which notifications to receive,
and on which channel—for example, one user may wish to receive new comment
notifications via email, but not via Slack.

<Figure>
  <Image
    src="/images/blog/notification-settings/notification-settings.jpg"
    alt="Notification settings example in an application"
    width={768}
    height={512}
    quality={90}
  />
</Figure>

Each option is individually customizable for each user on your app, and their
settings are saved under their user ID.

### Get started

If you’d like to get started, I’d recommend reading our guide on
[how to create a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).
In this guide we take you through every step required to set it up. If you’d
just like a quick overview, keep reading this article.

## How does it work?

User notifications settings are powered by our
[notification webhook](/docs/platform/webhooks#NotificationEvent), which
triggers events in your back end when users have unread notifications. Each
channel triggers separate webhook events, meaning you can handle each one
separately. Here’s an example of a `thread` webhook event on the `email`
channel.

```json highlight="4-5"
{
  "type": "notification",
  "data": {
    "channel": "email",
    "kind": "thread",
    "projectId": "my-project-id",
    "roomId": "my-room-id",
    "userId": "my-user-id",
    "threadId": "my-thread-id",
    "inboxNotificationId": "my-inbox-notification-id",
    "createdAt": "2021-10-06T01:45:56.558Z"
  }
}
```

This is a thread notification, meaning the user has an unread comment. Because
it was received on the `email` channel, it means you can create an email for the
`userId` mentioned in the event, letting them know they have an unread comment.

We have guides on how to set up webhooks and emails for
[unread comments in threads](/docs/guides/how-to-send-email-notifications-of-unread-comments)
and for
[unread mentions in text editors](/docs/guides/how-to-send-email-notifications-for-unread-text-editor-mentions).

### Enabling notifications on the dashboard

We have a new dashboard page, and you must enable each kind of notification on
here before you receive any events. You can set this up on four different
channels, Email, Slack, Microsoft Teams, and Web Push. On each channel you can
enable `thread` kinds, `textMention` kinds, and any custom notification kinds
too.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/images/blog/notification-settings/notifications-dashboard.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

Above we’re enabling `thread` notifications on the Email channel. Note that we
don’t recommend toggling these options in a production project before
[checking your project is ready to handle it](/docs/guides/what-to-check-before-enabling-a-new-notification-kind).

If you’re interested in more channels, feel free to reach out to us
[on Discord](/discord), as we’d love your feedback.

### Building the interface

Once you have the webhooks and the dashboard set up, you can build the
interface. We’ve created new React hooks that enable this. For example, adding a
checkbox to toggle `thread` notifications via email looks like this:

```tsx
import { useNotificationSettings } from "@liveblocks/react";

function NotificationSettings() {
  const [{ isLoading, error, settings }, updateSettings] =
    useNotificationSettings();

  if (isLoading || error || !settings.email) {
    return null;
  }

  return (
    <label>
      Receive thread notifications by email
      <input
        type="checkbox"
        checked={settings.email.thread}
        onChange={(e) =>
          updateSettings({ email: { thread: e.target.checked } })
        }
      />
    </label>
  );
}
```

Each user’s individual settings are automatically saved, and updates are applied
optimistically, meaning your UI responds immediately. With
[`useNotificationSettings`](/docs/api-reference/liveblocks-react#useNotificationSettings),
you can put together a settings panel that looks similar to the image further up
the page.

If you’re starting from scratch, we recommend following our guide detailing
[how to create a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel),
which will guide you through every step.

### Additional methods

On top of this, we’ve also released additional methods for
[Node.js](/docs/api-reference/liveblocks-node#get-users-userId-notification-settings)
and
[JavaScript](/docs/api-reference/liveblocks-client#Client.getNotificationSettings),
plus new
[REST APIs](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-users-userId-notification-settings).

## Example updates

We’ve added a
[new example to our gallery](/examples/notification-settings/nextjs-notification-settings)
which shows you how to set up a notifications panel. In this example, you can
sign in as different users, and edit their individual settings. We’ve also
updated our [Next.js Starter Kit](/nextjs-starter-kit), adding a new dialog menu
for changing notification settings.

<Figure>
  <Image
    src="/images/blog/notification-settings/starter-kit-dialog.png"
    alt="Starter kit dialog menu"
    width={768}
    height={512}
    quality={90}
  />
</Figure>

## Upgrade

To use the latest features, update your packages with the following command.

```bash
npx create-liveblocks-app@latest --upgrade
```

If you were previously on Liveblocks 2.15 or below, make sure to follow our
[upgrade guides](/docs/platform/upgrading) before updating.

## Get started now

We have some new guides that take you through how to get started.

- [How to create a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).
- [What to check before enabling a new notification kind](/docs/guides/what-to-check-before-enabling-a-new-notification-kind).

Plus we have our new API reference sections for each method.

- [`useNotificationSettings`](/docs/api-reference/liveblocks-react#useNotificationSettings)
- [`client.getNotificationSettings`](/docs/api-reference/liveblocks-client#Client.getNotificationSettings)
- [`Liveblocks.getNotificationSettings`](/docs/api-reference/liveblocks-node#get-users-userId-notification-settings)

## Contributors

<Contributors
  gitHubUsernames={[
    "flowflorent",
    "sugardarius",
    "ctnicholas",
    "adigau",
    "pierrelevaillant",
    "nvie",
    "ofoucherot",
  ]}
/>