Users | Knock Docs

Docs

Concepts

Users

Learn more about Users in Knock and see code examples to get started.

A User represents a person who may need to be notified of some action occurring in your product. A user is a type of recipient within Knock and is the most common type of entity that you may wish to send a notification to.

Sending user data to Knock

User data must be synchronized to Knock to send the user a notification or to reference that user in a notification. We refer to this process as identifying users.

Guidelines for use

User identifiers

The identifier for a user is important as it's the unique key that we will use to merge users and determine recipients for a notification. Generally, the best practice here is to use your internal identifier for your users as the id.

Required attributes

The following attributes are required for each user you identify with Knock.

Property	Description
id	An identifier for this user from your system, should be unique

Optional attributes

The following attributes are optional, depending on the channel types you decide to use with Knock.

Property	Description
email	The primary email address for the user (required for email channels)
name	The full name of the user
avatar	A URL for the avatar of the user
phone_number	The E.164 phone number of the user (required for SMS channels)
timezone	A valid tz database time zone string (optional for recurring schedules)

Storing user properties

In addition to the system attributes defined on the user schema above, Knock will keep track of any properties (key/value pairs) that you send to us. These traits are always merged onto a user and returned to you.

Traits are useful for when you need to perform additional personalization on a user, like denormalizing the current plan they're on so you can use this to determine the portion of a notification they should receive.

You can nest the properties you send as deeply as needed, and Knock will perform a deep merge with these properties on each subsequent upsert. Note that this means that existing properties cannot be explicitly removed, but you can overwrite them with a null value.

The user object

Once sent to Knock, the user object returned to you in the Knock payload looks like this:

Property	Description
id	The unique user identifier
properties*	Traits sent for the user are merged back onto the main user object
created_at	The created at time (provided by you)
updated_at	The last time we updated the user

* All properties appear at the top level of the user object.

Retrieving users

Users can be retrieved from Knock to see the current state of their properties using the users.get method.

Deleting users

Users can be deleted from Knock via the users.delete method. Deleting a user from Knock will have the following effect:

The user will no longer be able to be a recipient or an actor in a workflow
The user will no longer appear in the dashboard under the "Users" list
Any in-app messages that reference the user will be replaced by a "missing user" marker

Frequently asked questions

Commonly you'll want to send notifications to entities in your system that are not currently registered users in your product (think guests or invited users). In these situations, we recommend:

Identifying the user with a unique identifier, such as their email address, or with a prefix (guest_) to denote the different type.
Where possible, if the notified user becomes a registered user in your system then using our merge API to merge the guest user and the registered user to preserve message sending history.

It might feel counterintuitive to store registered users and non-registered users under a single collection in your Knock environment, but Knock should always be viewed as a cache of information about users and entities that may need to be notified in your system.

Yes, they are. Each environment has a separate, isolated set of users. If you need to share users across environments, you must re-identify them in each environment.

If you want to store and notify different types of users within your Knock environment, we recommend prefixing the id with the type. So if you had two distinct user types, owners and customers you can pass Knock ids like customer_123 and owner_456.

If you need to send a notification to an entity in your system you should have a look at modeling those as Objects. Objects can represent any non-user entity.

When you add new team members in the Knock dashboard, we automatically add them as "Users" within your Knock Development environment so you can send them notifications. We do this to help you with testing.

No, all users who are sent a notification are identified in your Knock environment and are persisted. If you have a use case here that you wish to discuss with us please get in touch.

If you need to edit or update a user's attributes in Knock, you can either use the identify a user endpoint or inline identification when triggering a workflow.