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) |
| 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