Knock in-app notifications

The Knock in-app notification channel provides an easy way to bring in-app notifications into your application. You can use our pre-built components to get up and running quickly with feeds, toasts, or inboxes embedded into your application, or you can build custom UI on top of our in-app API.

Related resources:

Understanding message statuses

Every in-app feed notification sent by Knock has a status of unseen, seen, or read. You can use these statuses to power notification badge counts, filtering, and mark-as-read functionality.

Here's more context on each status:

Unseen. The notification has not been rendered in the user's in-app feed, meaning the user hasn't seen the notification yet.
Seen. The notification has been rendered in the user's in-app feed, meaning the user opened the feed and saw the notification. If a notification has a status of seen it means that it has not yet been marked as read by the user.
Read. The notification has been marked as read by the user. There are a few ways notifications can be marked as read by users depending on the behavior you'd like to provide. We cover how this works in our own feed in the section below.

How the Knock in-app feed uses status

Message status is used to power a number of different features in the in-app feed.

Badge counting. By default, the Knock in-app feed badge counter will show users a count of how many unseen messages they have waiting for them in the feed. This means that as soon as they open the feed and see them the messages will be marked as seen and the badge count will go back to zero. Some apps prefer to show a count of unread messages on their badge counter; we default to unseen as it results in less noise and disruption for the user.
Mark as read. The Knock in-app feed lets users mark notifications as read in one of two ways. They can mark an individual item as read by clicking on it (which takes them to the URL assigned to that notification) or they can click "mark all as read" to mark all notifications in the feed as read.
Filtering. You can use the filter button at the top of the feed to filter messages based on their status. This helps users quickly access notifications they've read or haven't read so that they can quickly get to the high priority items in their feed.

Note that the functionality above is just the default for what we've provided in our in-app feed. If you'd like to use our message statuses in a different way, you can fork the Knock in-app feed and customize its behavior as you need to.

Archiving messages

Sometimes a user wants to remove a notification from their feed altogether. This is where notification archiving comes in. When a notification is archived, it is removed from the feed and is no longer visible to the end user.

In the Knock in-app feed, a message can be archived by clicking the "x" in the top-right corner of a given notification. The in-app feed component doesn't give users a way to see their archived notifications out-of-the-box, but if you'd like to incorporate this into your own in-app feed you can use the archived: only parameter on the GET feed request.

Customizing API response content

By default, the in-app feed API will return:

One or more actors associated with each in-app notification (when set), including all custom properties under each actor
All of the public variables (note: secret variables are never returned)
The entire workflow trigger data associated with each in-app notification
The recipient associated with each notification, including all custom properties set

In some situations, you may need control over exactly what the in-app feed API returns. This is where our API response filter can be used to completely customize the keys returned for the entities in your in-app feed responses.

Property	Description
vars	Apply a filter to the environment variables returned
actor	Apply a filter to all actors returned from the feed endpoint
recipient	Apply a filter to the recipient returned from the feed endpoint
data	Apply a filter to workflow trigger data returned from the in-app feed endpoint

Each property accepts the following:

A boolean to indicate whether this entity should be omitted or included, entirely (defaults to true).
An object with either except or only key paths for keys to exclude or include. Note: a nested keypath can be given using a ..

Example: customizing the actor data

As an example, if you want to customize the properties returned under an actor to only include id, name, and avatar you can set a response filter such as:

If you want to omit certain keys from the actor you can use the except keyword:

Or, if you want to exclude the actor from rendering you can set:

←Overview

Overview→