If your customers are asking for comments, mentions, and replies, and you're not sure where to start, you've come to the right place. In this post we go deep on the role that notifications play in collaboration, and how to design and deliver a great notifications experience for your users.

We'll start with the role that notifications play in great collaboration experiences and why it's so important to get them right, then we'll move on to the three primary notifications of collaboration—comments, mentions, replies—and a few key product considerations to take into account for each.

How notifications power collaboration

There was a time when collaboration primarily lived in general purpose, horizontal collaboration products. Now SaaS vendors are discovering that even in the most focused, vertically-oriented business applications, customers still expect the same level of collaboration functionality they'd find in products such as Slack, Dropbox, and Notion.

Your users expect collaboration functionality, but there's value in building it beyond just checking a box for customers. Helping users collaborate in your product drives the engagement loops that help other users find value, too. When a team member mentions me on a page in a given product, I log into that product to take a look and see what's needed of me. This loop—user A creates resource, user A engages user B, user B adds value, both users benefit—is called an engagement loop, and it's the driving force of any user-based collaboration product.

The role that notifications play in engagement loops

A closed engagement loop means more users collaborating on the work happening in your product. An open one means users missing out on value in your product that they don't realize is there.

We call it a loop because it keeps going. When a user leaves a comment, it's not being sent off into the ether, never to be heard from again. (That would be sad.) Instead, another relevant user is notified about it, takes a look, and contributes. This is why building a great notifications experience matters. If you offer a great collaboration experience in your product, but miss the mark on notifications, you're not closing the engagement loops that help bring users back into your product and find value.

In our blog post on notifications and product-led growth, we spoke about growth loops, and how a great notification is the difference between a new user signing up for your app and ignoring it. It's the same story here with engagement loops. A well crafted at-mention notification experience helps a recipient respond to their teammate. A poorly crafted notification experience leaves mentions and replies unanswered. In the seat-based model of SaaS workflow products, those moments of engagement and collaboration can be the difference between a net retention rate of 130%+ (🚀 and a net retention rate of < 100% (🚶‍♂️).

How to send great collaboration notifications

When you're adding collaboration to your product, there's usually one thing your customers have in mind: comments. They want to talk to their teammates about the work happening in your product. (We'll cover the other topics of collaboration—user assignment, task management, and reminders—in a separate post.)

When you think about "commenting", it helps to distill its functionality into three types: basic comments, at-mentions, and replies. Though these are all really just comments, you'll want to think about each type separately, as they deliver different functional affordances to your users and have different implications for your notifications system.

As we dive into each, we'll also discuss the a few key considerations to think about as you're implementing collaboration notifications: batching, priority, and recipient scope.

Comment notifications

If there's one thing to take away from this post, it's that you should be batching your comment notifications (if you aren't already.)

When a user leaves feedback on a page or a video, chances are they're going to have a lot to say. If you're not batching comment notifications today, that means those eleven comments left on a document turn into eleven emails in your user's inbox. Not good.

A batch sounds like a simple enough thing. In practice, batching is often more painful to build and maintain than it first appears. We have a separate post on the way about the technical how-tos and challenges of supporting batching; here we'll cover two product considerations to keep in mind.

Batching notifications: remember email subjects

When you're formatting the subject line string for a batched comment, "{n} comments left on {page_name}" seems like a natural place to start. Then you use your product for a few days and see this:

When email notification threading goes wrong

Since email clients thread emails by their subject line, any changes to that subject line result in a new conversation being started in your customer's inbox. Sometimes, this is the behavior you want, such as when you're sending users a general digest of the activity happening in your product. In cases that are specific to a given resource, you're giving your user multiple threads to track down about that resource, rather than filing all of its notifications into a single thread.

The simple way to solve this is removing counts from your batch notification subject line. By moving from "{n} comments left on {page_name}" to "New activity on {page_name}", you'll unify those notifications within a single thread.

Proper email notification threading

It's important to think about the email client behavior you want—threaded or unthreaded—for a given notification you're sending.

Mention notifications

A mention is a special thing. We introduce mentions into our products to give our users a way to call attention to something. When a user opts to use a mention instead of a regular comment, they're doing it because they want to make sure the recipient sees that message.

Mentions and in-app notification priority

There are a few ways you can call attention to mentions within your product. If you have an in-app feed, you can start by separating mentions out from batches, as we discussed above. This helps users see and manage those mentions as individual items they need to respond to.

An even better way to highlight mentions for recipients is to dedicate a surface area in your product for all of your high priority notifications. This could be separate tabs in your in-app feed for high priority notifications and general updates, as you see in Notion below, or a dedicated inbox page.

An example of different priority tabs in a notification feed

In Notion's Inbox, they surface both comments and @-mentions as high priority items. Pro: you can reply to every comment from your inbox. Con: you get every comment in your inbox.

Mentions and out-of-app notifications

When you're sending mention notifications across out-of-app channels such as email, push, or Slack, the same logic applies: your aim is to help users find those specific mentions in their inbox.

For email, that means considering the subject line threading behavior we mentioned above and how it impacts mentions. Here's an example from Linear of email threading done right.

A good example of email notifications with varying priority and threading behavior

When Linear sends you email notifications, mentions are broken out into their own threads by using an "{actor.name} mentioned you in a comment on [{issue.id}]{issue.name}" string format. Normal comments (and other lower priority notifications) have their subject lines formatted with a "{n} unread notifications on {team_name}" string format as a part of a batch notification. The end result: high priority notifications are easy to see in a user's inbox, lower priority notifications get batched to save room while still informing the user that something happened.

Reply notifications

Finally we have replies. The reply notification takes two of the considerations we've already introduced in this post—batching and priority—and introduces a third: recipient scope.

Recipient scope refers to the list of people that receive a given notification. When you invite a user to your account, the recipient scope is that individual user. When you leave a comment on a resource, the recipient scope is the list of followers of that resource.

When you think about your reply notification behavior, you have a choice to make: is a reply just treated as a normal comment or does it create a new thread with a new recipient scope?

This can be a hard concept to grok, so let's walk through an example.

Take a document. It has four followers: Ellie, Ray, Dennis, and John. When Ray leaves a comment on that document, all four followers (minus Ray, who just left the comment) receive a notification.

A document with one comment

Now say Dennis replies to Ray's comment: who gets a notification?

If you treat replies like any other comment, all four followers will get a notification. This certainly works, but it runs against the grain of why replies exist. We reply to a comment because we have something to say about that specific comment, not about the document as a whole.

Following this logic, we can articulate the list of people that care about that specific comment as the person who left that comment plus anyone that's replied to it. To bring it back to recipient scope, when a user replies to a comment, they start a new thread where the followers of that thread are the comment creator and anyone that's replied to it.

In our example above, when Dennis replies, a thread is created and Dennis and Ray are both added to its list of followers.

A document with a comment and a single reply

If Ellie were to reply to that thread, Ray and Dennis would both receive reply notifications, and Ellie would be added as a follower in the event that they reply to that thread.

A document with a comment and multiple replies

By considering our recipient scope, we've been able to match the functional intent of a reply to the notifications it sends.

Power delightful collaboration with Knock

As we've seen from this post, notifications get complicated fast. If you're looking to introduce collaboration notifications into your product and want a great set of APIs to keep things simple, you should try Knock.

We built Knock on the foundation of what we learned the hard way building past notification systems, including everything discussed in this blog post. You can quickly add support for batching, priority categorization, and user preferences, without having to build and maintain an entire notification system yourself. With our client and server-side SDKs and pre-made notification templates, you'll ship your notifications roadmap in a day, not a quarter.