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 == truein 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.
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
- An asserting (
"has") or negating (
"has not") condition operator.
- The expected delivery or engagement status case.
|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.|
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.
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):
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
refof the in-app step (by default named
- Select the negating "has not" operator.
- And finally, select the "been seen" status case option.
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
argument trio, with some special caveats:
variablewill always be either
operatorwill be a hierarchical comparison operator for a delivery status condition or an inclusionary operator for an engagement status condition.
argumentwill be a reserved status case string.
Below we provide example models for each of the status conditions made available in the editor.