Users
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.
Read more about 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 |
|---|---|
| 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) |
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 you like, but please remember that we will not deep merge these keys.
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
What do I do if my notification recipients aren't yet users?
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.
Are users unique per environment?
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.
What do I do if I have different types of users?
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.
How can I send a notification to a non-user entity?
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.
Why do I see my team members as users in Knock?
When you add new team members in the Knock dashboard, we automatically add those as "Users" within your Knock development environment so can send the notifications. We do this to help you with testing.
Can I avoid storing user data in Knock?
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.