Step conditions

Learn more about how to use step conditions within the Knock workflow builder.

Step conditions allow you to apply control flow to your workflow runs on a per-step basis. You can use the Knock conditions editor to associate one or more conditions with any step in your workflow. Then, for each workflow run, Knock will evaluate these conditions to determine if the step should execute.

Some examples of the kinds of step conditions you can design include:

Only send an email if an in-app notification was not previously read or seen.
Only send an in-app notification if the recipient.plan == "pro".
Only execute a delay step if delay == true in the workflow trigger.
Only send an email in your development environment if the recipient's email matches a particular domain.

See our guide on the Knock conditions model for more information about how conditions work across Knock and how to debug your conditions within your workflow runs.

In this guide, we cover features specific to step conditions, most importantly message status conditions.

Message status conditions

Message status conditions allow you to build a check for one workflow step that evaluates against the delivery or engagement status of a message sent from a preceding step. When building a step message status condition, you'll use the conditions editor to select:

Any preceding channel step that may produce a message, using it's ref.
An asserting ("has") or negating ("has not") condition operator.
The expected delivery or engagement status case.

Status cases

💡

Available statuses cases will vary. While you can reference any preceding channel step in a message status condition, you will be presented with a different set of options depending on the case (asserting or negating) and the target step's channel type. In-app feed channel steps support certain engagement status options ("seen but not read") that others do not. The "read" and "link clicked" status conditions often require that Knock tracking has been enabled.

Case	Limits	Description
skipped	-	The target step was skipped and did not generate a message.
failed delivery	-	The message failed to deliver and Knock has exhausted all retries.
sent	-	The message has been successfully sent to the delivery provider.
delivered	-	The message has been successfully sent to the delivery provider, and Knock has confirmed delivery to your recipient.
seen	In-app channels only	The message has been rendered in the feed.
seen but not read	In-app channels only	The message has been rendered in the feed, but not yet marked as read by your recipient.
read	In-app channel or Knock open tracking required	The message has been marked as read.
read but not clicked	Knock link tracking required	The message has been marked as read but no links have been clicked.
interacted with	In-app channels only	The recipient has clicked on the message.
link clicked	-	The recipient has clicked at least one link in the message.
archived	-	The message has been archived.

Evaluation timing

Knock evaluates message status conditions, like all conditions, immediately when executing a workflow step. This means that you may need to account for time between steps when building these conditions, especially those that require some amount of recipient engagement or delivery confirmation. See below for an example of using a delay step for this purpose.

Multiple messages

In certain cases, such as when using a channel group, a single channel step can produce multiple messages. In these cases, Knock uses the message with the highest status for the condition evaluation.

To determine each message's highest status, Knock looks at both its delivery status plus each of its engagement statuses, choosing the highest value status from the group. Knock uses the following combined delivery and engagement status hierarchy (ordered from lowest to highest):

undelivered
delivery_attempted
queued
not_sent
sent
delivered
seen
read
interacted + link_clicked
archived

Example: conditionally sending an email if an in-app notification was not seen

One common use-case for step conditions is conditionally sending a notification based on whether the recipient has seen a preceding notification delivered on another channel. You can think of this concept as channel escalation, or intelligent routing.

In order to implement this, your workflow will need:

An in-app notification channel step to send the initial message
A delay step so that we wait a period of time before executing the email step
An email channel step to send the escalated message

Next, we'll add a condition to our email channel step that will tell Knock to only send the email if the in-app notification has not yet been seen. To do this you will:

Select a "Step message status" condition type.
Select the ref of the in-app step (by default named in_app_feed_1).
Select the negating "has not" operator.
And finally, select the "been seen" status case option.

Setting a condition on an email step that passes when the message produced by the preceding in-app step has not been seen after a 5-minute delay.

That's all it takes to build intelligent message routing in Knock!

Advanced: How Knock models status conditions

The message status condition editor provides some useful abstractions on top of Knock's conditions model. Under the hood, Knock stores each status condition using our standard variable, operator, and argument trio, with some special caveats:

The variable will always be either refs.<ref>.delivery_status or refs.<ref>.engagement_status.
The operator will be a hierarchical comparison operator for a delivery status condition or an inclusionary operator for an engagement status condition.
The argument will be a reserved status case string.

Below we provide example models for each of the status conditions made available in the editor.

Step conditions

Message status conditions

Status cases

Evaluation timing

Multiple messages

Example: conditionally sending an email if an in-app notification was not seen

Advanced: How Knock models status conditions

Skipped cases

Failed delivery cases

Sent cases

Delivered cases

Seen cases

Read cases

Interacted cases

Link clicked cases

Archived cases