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.
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.
This is enabled by default and the notification kind is thread. Threads
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 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.