Update user function

An update user function updates a user stored in Knock as a step in your workflow. Use it when you need to change a user's properties or preferences based on workflow context so that downstream steps, audiences, or other workflows see the updated data.

Common use cases include syncing state from your trigger (for example, "last notified at"), making a user eligible for a dynamic audience so they'll receive a guide, or updating notification preferences from within a workflow.

By default, Knock updates the current workflow recipient (the user this run is for). Alternatively, you can select a property that resolves to a user ID (or use a literal user ID) to update a different user (for example, the actor or a user ID from your trigger data).

The update user step supports upserting. If you specify a user ID that does not yet exist in Knock, a new user will be created with the properties you set.

The update user step can update the user's notification preferences. This enables you to create workflow logic that updates which channels or workflows a user is opted into.

Set preferences using the preferences key on the user. The value should follow the structure of a PreferenceSet.

Preferences are deep-merged into the user's existing preference set. This means you can set individual preference keys across multiple update user steps without overwriting previously set values. For example, two sequential update user steps can each target a different part of the preference set and the results will be combined:

You can set any number of properties on the user. Each property has a key and a value. Properties can be configured as a JSON blob or as key-value pairs.

• Key. The property name. You can use an existing user property or define a new property.
• Value. The value to set. You can use Liquid (for example, {{ data.foo }} or {{ recipient.email }}) to resolve a dynamic value from workflow data, the recipient, the actor, or variables. You can also use a static value (for example, "bar" or true).

When an update user step executes, Knock deep-merges the configured properties into the existing user. This means:

• Top-level keys are merged into the existing user, adding new keys and replacing existing ones.
• Nested objects are recursively merged rather than replaced. If the existing user has a nested object and the update step sets a key inside it, only that key is updated — the rest of the nested object is preserved.

This is the same deep-merge behavior used by the identify API.

Update user steps do not support updating channel data. You cannot set or change channel data (for example, push tokens) via this step.

In addition, channel_data is not rendered in the workflow event success or error logging for these recipients, even when channel data is present on the user.

You can use the workflow run logs to debug update user steps. The logs render the full before/after diff view of the user so that you can verify the pre-state, the properties that were set, and the post-state.

Update user steps are also available in the management API and can be included when you show or upsert a workflow.