Notifications - Concepts
A quick overview of the concepts used in Liveblocks Notifications.
Inbox Notifications
In Liveblocks Notifications, everything resolves around inbox notifications. Each user can receive these notifications, and a list of them can be rendered in your application to create a notification tray. Inbox notifications can be sent either automatically by other Liveblocks products, or manually by calling a function on the server.
A user’s inbox notifications can be retrieved by a React hook or individually on your server, which is helpful after receiving a notification webhook event. Here’s an example of an inbox notification object for a custom notification.
To build a notification tray, you can use a combination of default components and hooks.
Project-based
Inbox notifications are project-based, which means that a user can receive notifications that were sent from other rooms. This differs to other Liveblocks products which are room-based, and rely on users inhabiting the same space.
Project-based components require only
LiveblocksProvider
in React, which is different to other room-based Liveblocks products which also
require RoomProvider.
Notification kinds
Each inbox notification has a kind, and this represents the type of
notification it is. A kind is either a custom string prefixed with $ (e.g.
$myCustomNotification) when sending a custom notification, or specific string
set by Liveblocks (e.g. thread) when it’s sent by a Liveblocks product.
Custom notifications
A custom notification is a notification that you specify yourself, and can contain any content.
Custom notifications can be sent using
liveblocks.triggerInboxNotification
on the server, and the kind must always begin with a $, for example
$myCustomNotification.
When you trigger an inbox notification, you pass the activity data, which represents the events that happened. If you’d like to update an existing inbox notification when a new activity happens, you can configure the custom notification to use batching.
Liveblocks notifications
Comments can send thread notifications
for you automatically, notifying you of events such as a mention, or a new reply
in a thread you’re participating in. Additionally,
text editors can send
textMention notifications whe users are mentioned inside the editor.
These are enabled by default and the notification kind names are thread and
textMention. Threads and mentions leverage Notifications behind-the-scenes to
keep track of unread comments so viewing a thread will also mark its inbox
notification as read, and vice versa.
If you use the default
Thread component, it will
automatically handle marking threads as read when they are viewed and show
unread indicators when there are unread comments in threads you are
participating in.
Notification batching
Batching allows you to group multiple activities into a single notification.
This is useful for reducing the number of notifications that are sent to the
user, and can be enabled on custom notification kinds. It’s always enabled for
Liveblocks thread notifications, where new comments in a thread are grouped
into a single notification.
Within the “Notifications” page in the dashboard, you can add a
custom kind and enable batching. When it’s enabled, triggering an inbox
notification activity for a specific subjectId, will update the existing inbox
notification instead of creating a new one.
An inbox notification can have up to 50 activities, if you exceed this number, a
new inbox notification will be created. Liveblocks textMention notifications
are never batched.
Notification channels
You can also send notifications on other channels, such as email or Slack, letting users know when they’ve missed in-app notifications. Using our dashboard and hooks you can allow users to set their own notification settings.
There are default channel types for email, Slack, Microsoft Teams, and Web Push. Each channel works the same, but you can enable different settings for each and use them differently. Learn more about notification channels in our email notifications page.
Permissions
Access tokens
When using access token authentication, Liveblocks disregards the permissions specified in the tokens and returns all notifications created for the user. Consequently, a user will receive notifications for mentions in comments within rooms they do not have access to.
For greater control over notification permissions, we recommend utilizing ID tokens.
ID token
When using ID token authentication, Liveblocks reads the permissions set on the room, and uses these to deliver notifications that the user is authorized to view.
Email notifications
It’s possible to send email notifications to your users, listing all their unread inbox notifications using a webhook event that Liveblocks provides. Learn more about email notifications.