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 to get information on unread mentions and replies, and start rendering emails with HTML or React.

// Get email data as React JSXconst emailData = await prepareThreadNotificationEmailAsReact(  liveblocks,  event);
let email;switch (emailData.type) {  // The user has an unread mention  case "unreadMention": {    email = (      <div>        <div>          @{emailData.comment.author.id} at {emailData.comment.createdAt}        </div>        <div>{emailData.comment.reactBody}</div>      </div>    );    break;  }
  // The user has multiple unread replies  case "unreadReplies": {    email = (      <div>        {emailData.comments.map((comment) => (          <div key={comment.id}>            <div>              @{comment.author.id} at {comment.createdAt}            </div>            <div>{comment.reactBody}</div>          </div>        ))}      </div>    );  }}

You can customize this further, resolving user and room IDs into data, allowing you to render names instead of IDs. You can also add custom React components to the comment bodies, helpful for custom stying.

// Get email data as React JSXconst emailData = await prepareThreadNotificationEmailAsReact(  liveblocks,  event,  {    resolveUsers: async ({ userIds }) => {      const usersData = await (userIds);
      return usersData.map((userData) => ({        name: userData.name,        avatar: userData.avatar.src,      }));    },    // ...    components: {      // `user` is the optional data returned from `resolveUsers`      Mention: ({ element, user }) => (        <span style={{ color: "red" }}>@{user.name}</span>      ),
      // ...    },  });

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",  react: `    <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, and using Resend to send an email.

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.

We use cookies to collect data to improve your experience on our site. Read our Privacy Policy to learn more.