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.
Every in-app feed notification sent by Knock has a status of
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
seenit 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.
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
unseenmessages 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
seenand the badge count will go back to zero. Some apps prefer to show a count of
unreadmessages on their badge counter; we default to
unseenas 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
- 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.
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.
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.
|Apply a filter to the environment variables returned
|Apply a filter to all actors returned from the feed endpoint
|Apply a filter to the recipient returned from the feed endpoint
|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
- An object with either
onlykey paths for keys to exclude or include. Note: a nested keypath can be given using a
As an example, if you want to customize the properties returned under an actor to only include
avatar you can set a response filter such as:
If you want to omit certain keys from the actor you can use the
Or, if you want to exclude the actor from rendering you can set: