Filtering feeds

When building an in-app notifications UI, you can filter notifications to increase their relevancy for your users. This is particularly useful for:

• A multi-tenant SaaS application where users need to see tenant-specific notifications
• Applications that need to show contextual notifications for specific resources
• Separating notifications by engagement status (unread, read, seen, archived)
• Separating notifications by a custom property (e.g. priority: "high", status: "incomplete")

This page covers how to filter the feed API using defaultFeedOptions. These filters apply to all feed results, including real-time updates and badge counts for unseen or unread notifications.

In a multi-tenant SaaS application, users often belong to one or more tenants, and their notifications should be scoped to the tenant they're currently viewing.

For example, consider a user named jane in a document editing app. Jane's profile is connected to two workspaces: acme-inc and superior-products. When Jane is active in the acme-inc workspace, she should only see notifications relevant to that workspace.

Knock implements this concept through Tenancy, where workflow triggers can be "tagged" with a tenant identifier. This identifier can be used to apply tenant overrides and scope in-app notifications. Here's how it works:

To scope the in-app feed by the user's current tenant:

By default, filtering by tenant includes all notifications that either:

• Include the specified tenant
• Were sent without a tenant identifier

If you need to show only notifications for a specific tenant, you can add has_tenant: true to your filter:

To show notifications from a specific workflow in your in-app feed, use the source filter. For example, in a document collaboration application, you might want to show only notifications from the new-comment workflow:

Note: Currently, filtering by multiple sources is not supported.

You can filter the feed using properties from the data payload in your trigger step. This provides a flexible way to query feed data based on your system's entities. For example, to show comment notifications for a specific page in your document editing app:

To filter the feed by this data:

Keep in mind the following limitations when filtering by data:

• Filters use AND logic. A notification must match every key-value pair you provide, so you cannot match one key or another (e.g., projectId or ownerId) in a single request.
• Each key accepts a single value. If you pass an array of values (e.g., { status: ["open", "pending"] }), Knock returns an error.
• You can only filter by top-level keys in your data payload (e.g., data.foo is supported, but data.foo.bar is not).
• Only exact value matching is supported, including type. Partial matches and comparison operators are not available.

For a complete list of filtering options, refer to the API reference. These options are available through the FeedClientOptions type, which you can use to:

• Set default filters in the feed constructor
• Override defaults for individual fetch operations