Comments - Email notifications

Using Liveblocks webhooks, it’s possible to trigger your API endpoints when certain events occur, such as a thread being created, or a comment being modified. One use for these events is sending unread comment notifications, for example via email or Slack.

An email titled 'New notifications' showing two comments and a link to the thread

Inbox notifications

Email notifications are built around the concept of inbox notifications, which are different from “normal” notifications in the sense that they can group multiple activities together and evolve over time, which makes more sense when sending email notifications because it helps to avoid sending too many emails. In the case of Comments, inbox notifications are grouped per thread, which means that if there are 4 new comments in a thread you’re participating in, you will have a single inbox notification for it, instead of 4 “normal” notifications.

Learn more about Notifications for Comments in the overview page.

Sending email notifications with webhooks

Using Liveblocks webhooks you can listen to a range of events such as comments being deleted, or comment reactions being added. On your dashboard you can create a webhook for a project, and select which events you’d like to listen to.

The endpoint URL you pass will receive request with relevant data when the event occurs. The webhook event built for creating these unread notification emails is called "notification", and by default is sent up to every 30 minutes to each user, though this can be customized in the webhooks dashboard. Here’s an example of an event object that’s sent when a user receives a new (or updated) inbox notification.

const event = {  type: "notification",  data: {    channel: "email",    type: "thread",    projectId: "my-project-id",    roomId: "my-room-id",    threadId: "th_d75sF3...",    inboxNotificationId: "in_xt3p7ak...",    userId: "my-user-id",    createdAt: "2021-10-06T01:45:56.558Z",  },};

Your endpoint

In your endpoint, you can use this event object with functions such as liveblocks.getThread and liveblocks.getInboxNotification, which will return the thread and inbox notification for the event.

// Data from the `notification` eventconst { roomId, threadId, inboxNotificationId, userId } = event.data;
// Get the thread with the unread comments insideconst thread = await liveblocks.getThread({ roomId, threadId });
// { type: "thread", id: "th_d75sF3...", ... }console.log(thread);
// Get the inbox notification, which details when the user last read the threadconst inboxNotification = await liveblocks.getInboxNotification({  inboxNotificationId,  userId,});
// { kind: "thread", readAt: Date<2024-07-13T14:32:50.697Z>, ... }console.log(inboxNotification);

Once you have the thread, and the inbox notification, you can use stringifyCommentBody to transform unread comments into an email-compatible format.

// Get all unread commentsconst unreadComments = thread.comments.filter((comment) =>  inboxNotification.readAt ? comment.createdAt > inboxNotification.readAt : true);
// Transform the oldest unread comment into HTMLconst commentHtml = await stringifyCommentBody(unreadComments[0].body, {  format: "html",});
// "<p>Hello world!</p>"console.log(commentHtml);

You can then send an email containing the comment to the owner of userId received in event.

const emailAddress = (userId);
// Send email to the user that received the inbox notification({  from: "hello@my-company.com",  to: emailAddress,  title: "Unread comment",  html: `    <h1>Unread comment</h1>    ${commentHtml}  `,});

Here’s an example with every step linked together, along with the code necessary to verify a webhook request is valid.

If you’re planning on building this, we recommend learning more in our how to send email notifications guide, as it’s possible to create much more complex emails than this simple example.

Permissions

When you receive a notification webhook event, it's essential to verify if the user has access to the room before sending an email. Liveblocks lacks the necessary information to determine if a user has access to a room. For instance, we create an inbox notification when a user is mentioned in a comment. In this user's client context, we can determine if they have access to the notification thanks to the token generated for that user. However, when we send a notification webhook event, we lack this information.

Access token authentication

If you are using access tokens, this will always be true, Liveblocks will never have the information.

ID token authentication

If you are using ID tokens, Liveblocks already possesses certain information about the permissions you have configured for each room, specifying which users and groups have access. However, what we currently lack is the relationship between a user and a group. At present, you need to verify user access before sending an email. We do, however, plan to include full permissions info in Liveblocks in our future updates. If you're interested in learning more about this feature, please feel free to reach out to us.

Webhook events

There are more webhook events than just the NotificationEvent event used above—a number related to Comments are available to use.

There are also more events, for example you can trigger events when users enter or leave rooms. We recommend reading our guide on testing webhooks locally to get started.

Retrieving and modifying Comments data

Here’s every Comments-related @liveblocks/node function. Each also has a corresponding REST API, you can find more info by following the links.