Setting preferences

Learn more about how to set preferences for your recipients.

You can read more about modeling preferences and preferences in general in the Preferences guide. In the guide below, we walk through the technical details of integrating the Knock preferences model into your product.

Preferences live under a user or an object and are used to structure a set of rules about what notifications a recipient should receive (called a PreferenceSet). They are designed to be flexible and expressive to accommodate complex scenarios like per-resource muting (example: muting notifications for a given Slack channel).

Backend integration

In the following examples, you'll see how to integrate preferences into your backend codebase using one of our server-side SDKs.

Getting preferences

You can retrieve a given set of preferences using the getPreferences method. Please note that even if the preferences are not set, you will receive an empty PreferenceSet in response.

Setting preferences

You can update an entire set of preferences using the setPreferences method. This will overwrite any existing preferences set:

Setting preferences with conditions

You can use the setPreferences method to also set preferences with conditions that are evaluated. Please refer to the documentation on preference conditions to learn more.

See an example. Follow this link to see an example of how to set preferences with conditions.

Bulk setting user preferences

You can update the preferences of up to 1000 users in a single batch by using the users.bulkSetPreferences method. This executes an asynchronous job which will overwrite any existing preferences for the users provided. You can track the progress of the BulkOperation returned via the bulk operation API.

See an example. Check out our example app to see the bulk preferences API being used within the context of a collaboration app.

Setting per-tenant preference sets

By default, all preference sets are set with an id of default. To set a per-tenant preference set for a user you must pass the as the id of the preference set. At workflow execution time, Knock will select a matching per-tenant preference set for the workflow run when a tenant is passed into your workflow trigger.

In the case in which the per-tenant preference set doesn't exist, the default preference set is used.

Setting preferences inline during a workflow trigger

Please note: setting preferences inline will always upsert the preference set, meaning that changes will overide any existing preferences. We generally recommend against using inline preferences to ensure the integrity of your data.

Preferences can also be set during a workflow trigger using inline identify. One or more preference sets (including per-tenant preferences) can be upserted by passing a dictionary of preference sets, where each key in the dictionary is the preference set ID.

Unlike the setPreferences method, setting preferences inline requires you to explictly provide the default preference set key when updating default preferences.

Client integration

The preferences API can also be invoked from the client, provided you have authenticated a user first and have a valid API token.

Note: at this time only the current user's preferences can be retrieved or updated.

Retrieve the preferences for the current user

Set the preferences for the current user

See an example. Check out our example app for real examples of getting and setting preferences using our client library.