React UI Node.js Comments Tutorials Webhooks Notifications

How to send email notifications of unread comments

Liveblocks Comments allows you to build a commenting experience. With our webhooks and REST API, it’s possible to aggregate a list of unread comments from the last 30 minutes into a single email, and send it to your users. Notifications can also be displayed in your app using useInboxNotifications and the InboxNotification component.

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

Just in case

If you’re looking for a guide on sending an email containing one comment, immediately after every single comment is created, then sending emails when comments are created is for you.

What we’re building

In this guide we’ll be learning how to send emails notifying users about unread comments, and more specifically, we’ll be looking at how to:

Trigger events based on unread comments using the NotificationEvent webhook event.
Fetch unread thread data using the @liveblocks/node package.
Build an email containing correctly formatted text.
Send an email notification containing a list of unread comments in thread format with Resend.

Have a project ready

This guide assumes you already have a Liveblocks Comments project set up. If you haven’t already got one, you can get started with Comments, and come back after you’re set up. You could also use our Next.js Starter Kit which has this set up already.

What are 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.

Using webhooks

Liveblocks provides a number of webhooks that can send requests to your API endpoint when certain events occurs. One webhook we provide is the NotificationEvent webhook, which is triggered for each participating user in a thread, 30 minutes after activity has occurred, and this can be used to send emails to your users.

The information it returns allows you to retrieve comments that have not yet been read by the user, making it possible to aggregate multiple unread comments into a single notification email. Let’s take a look at how to set this up.

Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in your project. In this guide, we’ll be using a Next.js route handler (API endpoint) as an example, but other frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the headers and body from the request. Here’s the basic endpoint we’ll be starting from:

export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Handle webhooks and notifications  // ...
  return new Response(null, { status: 200 });}

Create this endpoint in your project, and make it available on localhost at the following URL:

/api/liveblocks-notifications

Make a note of this endpoint URL, as you’ll be using it later.

Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a tool such as localtunnel or ngrok which allow you to temporarily put your localhost server online.

If your project is running on localhost:3000, you can run the following command to generate a temporary URL that’s available while your localhost server is running:

$npx localtunnel --port 3000

localtunnel generates a base URL that can be placed into the Liveblocks webhooks dashboard for quick testing. To use this, take the full address of your webhook endpoint, and replace the domain in your localhost address with the generated URL.

# Take your local URLhttp://localhost:3000/api/liveblocks-notifications
# Replace localhost with the generated domain, then copy ithttps://my-localtunnel-url.loca.lt/api/liveblocks-notifications

You now have a URL that can be used in the webhooks dashboard.

Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard inside your Liveblocks project, and tell the webhook to trigger when a comment has been created.

Select your project
From the Liveblocks dashboard, navigate to the project you’d like to use with webhooks, or create a new project.
Go to the webhooks dashboard
Click on the “Webhooks” tab on the menu at the left.
Create an endpoint
Click the “Create endpoint…” button on the webhooks dashboard to start setting up your webhook.
Add your endpoint URL
Enter the URL of the endpoint. In a production app this will be the real endpoint, but for now enter your localtunnel URL from earlier.
Get your webhook secret key
Click “Create endpoint” at the bottom, then find your “Webhook secret key” on the next page, and copy it.
Webhooks dashboard is set up!
Note that you can filter specifically for notification events, but we’re ignoring this for now so we can test more easily. Let’s go back to the code.

Verify the webhook request

The @liveblocks/node package provides you with a function that verifies whether the current request is a real webhook request from Liveblocks. You can set this up by setting up a WebhookHandler and running verifyRequest.

Make sure to add your “Webhook secret key” from the Liveblocks dashboard—in a real project we’d recommend using an environment variable for this.

import { WebhookHandler } from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // Send notifications  // ...
  return new Response(null, { status: 200 });}

Check the event and notification permissions

After verifying the request, we can then check we’re receiving the correct type of event, and check if the user should receive a notification. Liveblocks doesn’t have knowledge of your permissions system on the back end, so it’s your responsibility to check if this user should receive a notification.

import { WebhookHandler } from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    // Send notifications    // ...  }
  return new Response(null, { status: 200 });}

We now have the roomId, threadId, inboxNotificationId. and userId of the created notification, along with some other information.

Get comment and thread data

Threads vs comments

Note that a thread is different to a comment—a thread is “top-level”, and each thread contains a list of comments. When you create a thread with useCreateThread, you also create the first comment in the thread.

The next step is to use the Liveblocks client from @liveblocks/node to retrieve the inbox notification, and the corresponding thread’s data. To do this we’ll need to add our project’s secret key to the Liveblocks client, before awaiting the following functions: getInboxNotification and getThread.

import { Liveblocks, WebhookHandler } from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
// Add your secret key from a project's API keys dashboardconst API_SECRET = "";const liveblocks = new Liveblocks({ secret: API_SECRET });
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    try {      // Get thread and notification      const [thread, inboxNotification] = await Promise.all([        liveblocks.getThread({ roomId, threadId }),        liveblocks.getInboxNotification({ inboxNotificationId, userId }),      ]);
      // Send notifications      // ...    } catch (err) {      console.log(err);      return new Response("Could not fetch notification data", { status: 500 });    }  }
  return new Response(null, { status: 200 });}

Get the unread comments

The next step is to get each unread comment by comparing the readAt time in the inbox notification with the createAt time on each comment. We’re also filtering out each comment with no body, which represents a deleted comment.

import { Liveblocks, WebhookHandler } from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
// Add your secret key from a project's API keys dashboardconst API_SECRET = "";const liveblocks = new Liveblocks({ secret: API_SECRET });
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    try {      // Get thread and notification      const [thread, inboxNotification] = await Promise.all([        liveblocks.getThread({ roomId, threadId }),        liveblocks.getInboxNotification({ inboxNotificationId, userId }),      ]);
      // Get unread comments (and filter out deleted comments)      const readAt = inboxNotification.readAt;      const unreadComments = thread.comments        .filter((comment) => (readAt ? comment.createdAt > readAt : true))        .filter((comment) => comment.body !== undefined);
      // No unread comments, therefore notification needed      if (unreadComments.length === 0) {        return new Response(null, { status: 200 });      }
      // Send notifications      // ...    } catch (err) {      console.log(err);      return new Response("Could not fetch notification data", { status: 500 });    }  }
  return new Response(null, { status: 200 });}

If there are no unread notifications, then we’re choosing not to send an email.

Generating HTML for the email

Now that we have the comment data, we have one more step before sending the notifications—formatting each comment’s text, found inside comment.body, and generating the HTML for our email.

By using await stringifyCommentBody, we can convert each comment into plain HTML. In this code snippet, you can see we’re looping through each comment, and replacing comment.body with an HTML string.

import {  Liveblocks,  WebhookHandler,  stringifyCommentBody,} from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
// Add your secret key from a project's API keys dashboardconst API_SECRET = "";const liveblocks = new Liveblocks({ secret: API_SECRET });
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    try {      // Get thread and notification      const [thread, inboxNotification] = await Promise.all([        liveblocks.getThread({ roomId, threadId }),        liveblocks.getInboxNotification({ inboxNotificationId, userId }),      ]);
      // Get unread comments (and filter out deleted comments)      const readAt = inboxNotification.readAt;      const unreadComments = thread.comments        .filter((comment) => (readAt ? comment.createdAt > readAt : true))        .filter((comment) => comment.body !== undefined);
      // No unread comments, therefore notification needed      if (unreadComments.length === 0) {        return new Response(null, { status: 200 });      }
      // Convert comments to plain HTML and return { body: "<p>...</p>", ...comment } format      const htmlComments = await Promise.all(        unreadComments.map((comment) => ({          body: stringifyCommentBody(comment.body, { format: "html" }),          ...comment,        }))      );
      // Create final HTML for email      let html = `<h1>New notifications</h1>`;      for (const comment of htmlComments) {        html += `          <div>Comment by ${comment.userId} at ${comment.createdAt}</div>          ${comment.body}        `;      }      html += `        <a href="https://my-company.com/room/${roomId}">Go to thread</a>      `;
      // Send notifications      // ...    } catch (err) {      console.log(err);      return new Response("Could not fetch notification data", { status: 500 });    }  }
  return new Response(null, { status: 200 });}

This snippet outputs fairly simple formatting, for example it renders a user IDs (e.g. @jory.quispe) instead of a names (e.g. @Jory Quispe), but you can create more complex formatting easily by using more complex stringifyCommentBody options.

Send notification emails

Now that the HTML has been generated, we can send the notification emails. Earlier we retrieved userId, the ID of the user that’s receiving the notification. You can use this to get the user’s email address, before sending the email itself.

userIds

This is the same userId that you passed to resolveUsers in your liveblocks.config.ts file.

import {  Liveblocks,  WebhookHandler,  stringifyCommentBody,} from "@liveblocks/node";
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
// Add your secret key from a project's API keys dashboardconst API_SECRET = "";const liveblocks = new Liveblocks({ secret: API_SECRET });
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    try {      // Get thread and notification      const [thread, inboxNotification] = await Promise.all([        liveblocks.getThread({ roomId, threadId }),        liveblocks.getInboxNotification({ inboxNotificationId, userId }),      ]);
      // Get unread comments (and filter out deleted comments)      const readAt = inboxNotification.readAt;      const unreadComments = thread.comments        .filter((comment) => (readAt ? comment.createdAt > readAt : true))        .filter((comment) => comment.body !== undefined);
      // No unread comments, therefore notification needed      if (unreadComments.length === 0) {        return new Response(null, { status: 200 });      }
      // Convert comments to plain HTML and return { body: "<p>...</p>", ...comment } format      const htmlComments = await Promise.all(        unreadComments.map((comment) => ({          body: stringifyCommentBody(comment.body, { format: "html" }),          ...comment,        }))      );
      // Create final HTML for email      let html = `<h1>New notifications</h1>`;      for (const comment of htmlComments) {        html += `          <div>Comment by ${comment.userId} at ${comment.createdAt}</div>          ${comment.body}        `;      }      html += `        <a href="https://my-company.com/room/${roomId}">Go to thread</a>      `;
      // Get the user's email address from your database      const emailAddress = await (userId);
      // Send email to the user's email address      // send({      //   from: "hello@my-company.com",      //   to: emailAddress,      //   title: "New comment",      //   html,      // });    } catch (err) {      console.log(err);      return new Response("Could not fetch notification data", { status: 500 });    }  }
  return new Response(null, { status: 200 });}

Sending emails with Resend

Resend is a great tool for easily sending emails, and in this code example, we’re using it to send the notifications to each user. Make sure to add your API key from the Resend dashboard before running the code.

route.ts

import {  Liveblocks,  WebhookHandler,  stringifyCommentBody,} from "@liveblocks/node";import { Resend } from "resend";
// Create Resend client (add your API key)const resend = new Resend("re_123456789");
// Add your webhook secret key from a project's webhooks dashboardconst WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);
// Add your secret key from a project's API keys dashboardconst API_SECRET = "";const liveblocks = new Liveblocks({ secret: API_SECRET });
export async function POST(request: Request) {  const body = await request.json();  const headers = request.headers;
  // Verify if this is a real webhook request  let event;  try {    event = webhookHandler.verifyRequest({      headers: headers,      rawBody: JSON.stringify(body),    });  } catch (err) {    console.error(err);    return new Response("Could not verify webhook call", { status: 400 });  }
  // When an inbox notification has been created  if (event.type === "notification") {    const { roomId, threadId, inboxNotificationId, userId } = event.data;
    // Check if user has access to room    if (!(userId, roomId)) {      return new Response(null, { status: 200 });    }
    try {      // Get thread and notification      const [thread, inboxNotification] = await Promise.all([        liveblocks.getThread({ roomId, threadId }),        liveblocks.getInboxNotification({ inboxNotificationId, userId }),      ]);
      // Get unread comments (and filter out deleted comments)      const readAt = inboxNotification.readAt;      const unreadComments = thread.comments        .filter((comment) => (readAt ? comment.createdAt > readAt : true))        .filter((comment) => comment.body !== undefined);
      // No unread comments, therefore notification needed      if (unreadComments.length === 0) {        return new Response(null, { status: 200 });      }
      // Convert comments to plain HTML and return { body: "<p>...</p>", ...comment } format      const htmlComments = await Promise.all(        unreadComments.map((comment) => ({          body: stringifyCommentBody(comment.body, { format: "html" }),          ...comment,        }))      );
      // Create final HTML for email      let html = `<h1>New notifications</h1>`;      for (const comment of htmlComments) {        html += `          <div>Comment by ${comment.userId} at ${comment.createdAt}</div>          ${comment.body}        `;      }      html += `        <a href="https://my-company.com/room/${roomId}">Go to thread</a>      `;
      // Get the user's email address from your database      const emailAddress = await (userId);
      // Send email to the users' email addresses      try {        const data = await resend.emails.send({          from: "My company <hello@my-company.com>",          to: emailAddress,          subject: "New comment",          html,        });      } catch (err) {        console.error(err);      }    } catch (err) {      console.log(err);      return new Response("Could not fetch notification data", { status: 500 });    }  }
  return new Response(null, { status: 200 });}

Recap

Great, we’re successfully sending email notifications after new comments are created! In this guide we’ve learned:

How to use webhooks and the NotificationEvent.
How to use the @liveblocks/node package to unread thread data.
How to shape a threads into HTML with stringifyCommentBody.
How to send email notifications with Resend.

How to send email notifications of unread comments

What we’re building

What are inbox notifications?

Using webhooks

Create an endpoint in your project

Testing webhooks locally

Set up webhooks on the Liveblocks dashboard

Select your project

Go to the webhooks dashboard

Create an endpoint

Add your endpoint URL

Get your webhook secret key

Webhooks dashboard is set up!

Verify the webhook request

Check the event and notification permissions

Get comment and thread data

Get the unread comments

Generating HTML for the email

Send notification emails

Sending emails with Resend

Recap

How to test webhooks on localhost

How to add users to Liveblocks Notifications

How to send email notifications of unread comments

Select your project

Go to the webhooks dashboard

Create an endpoint

Add your endpoint URL

Get your webhook secret key

Webhooks dashboard is set up!

Related guides

How to test webhooks on localhost

How to add users to Liveblocks Notifications