Delay function

A delay function does just what it sounds like: it delays the execution of the workflow for some amount of time, then proceeds to the next step. There are two types of delays we support in Knock today: "wait for set interval" and "wait for a dynamic duration".

Wait for a set interval

The "wait for set interval" delay type waits for an interval of time (provided by you in the workflow editor) and then proceeds to the next step.

Set interval delay functions are helpful for the following use cases:

• Check to see if a user's seen or read an in-app message before sending an email
• Remind a user about a pending invite they haven't accepted

Wait for a dynamic duration

You can also set the length of your delay duration dynamically using a variable. You can use any of the data, recipient, actor, or environment variables associated with the workflow run to set your duration.

When specifying a dynamic delay duration you can provide either:

• An ISO-8601 timestamp (e.g. 2022-05-04T20:34:07Z) which must be a datetime in the future
• A relative duration unit (e.g { "unit": "seconds", "value": 30 })

A dynamic duration must be available to be resolved via the key you specify on the given schema, meaning that if you specify a key of delayUntil in your Data schema, your workflow trigger data must contain either an ISO-8601 timestamp or a valid duration unit.

Timestamp-based delays are helpful for reminders about resources in your product that need to be completed or addressed by a specific point in time. As an example, if a user has a task that's due three days from now and you want to remind them 24 hours before it's due, you can set a timestamp delay for the task's due date minus 24 hours.

Using workflow cancellation with delays

In cases where you're waiting to see if a user will complete an action before sending a notification, you can use our workflow cancellation API to ensure a user doesn't receive an unnecessary reminder.

If the user completes the action you were going to remind them about, cancel the workflow to keep any additional notifications from being sent.

Frequently asked questions

How do I set per-environment delay periods?

Often when you're testing your Knock workflows, you'll want your delay durations to be shorter in non-production environments to aid with testing. To set per-environment delay duration you can:

• Create a new variable under "Developers > Variables" with a relative duration as JSON ({ "unit": "seconds", "value": 30 }) and a name of delayDuration
• Set your delay duration to "Wait until a dynamic interval"
• Specify that your delay duration will come from an environment variable
• Set the key to delayDuration, which will resolve the delay duration from the variable you created
• You can now override the variable per environment to specify a shorter, or longer window as needed

How can I cancel an open delay

You can use the workflow cancellation API to cancel a delayed workflow. You must use a unique cancelation key to cancel a previously triggered workflow run.

How long can a workflow be delayed?

A workflow can be delayed for a maximum of 365 days (1 year).

What are the guarantees around delayed workflows?

Knock will ensure that your delayed workflow run will execute within ~1 - 5s of the delayed time.

How can I see delayed workflow runs?

We currently don't have a way to view all delayed workflow runs with pending messages. If this is a feature you need, please reach out as we'd love to hear your use case.