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.

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.

Please note: The maximum number of characters for the identifier is 256 and it cannot contain a "/". You cannot change a user's id once it has been set, so we recommend you use a non-transient `id` like a primary key rather than a phone number or email address.

Required attributes

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

idAn 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.

emailThe primary email address for the user (required for email channels)
nameThe full name of the user
avatarA URL for the avatar of the user
phone_numberThe E.164 phone number of the user (required for SMS channels)
timezoneA 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 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:

idThe unique user identifier
properties*Traits sent for the user are merged back onto the main user object
created_atThe created at time (provided by you)
updated_atThe 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