Delay function | Knock Docs

Docs

Platform

Workflows

Delay function

Learn more about the delay workflow function within Knock's notification engine.

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 four types of delays we support in Knock today: "wait for fixed interval", "wait for a dynamic period", "wait until a relative timestamp", and "wait until a time window."

By default, that continuation uses the latest published version of the workflow.

Wait for a fixed interval

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

Fixed 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

A fixed interval can be at most 365 days.

Wait for a dynamic period

You can also set the length of your delay 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 period you must provide one of the following:

An ISO-8601 timestamp (e.g. 2027-05-04T20:34:07Z) which must be a datetime in the future
A duration unit (e.g { "unit": "seconds", "value": 30 })
A window rule (e.g { "frequency": "daily", "hours": 9, "minutes": 30 })

A dynamic delay 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, a valid duration unit, or a valid window rule under that key.

When the specified key is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the delay will be skipped. If the resolved time is more than 365 days after the delay step runs, Knock logs an error and halts the entire workflow run. See how long a workflow can be delayed for alternatives.

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.

An example timestamp

You can then reference that in your delay step settings as data.delayUntil.

A duration will take the current time that the delay step is executing and add the duration to it to produce the delay until time. A duration object is an entity that you can set on recipients, tenants, environment variables, or in your data payload and reference on your delay step.

Duration properties

Variable	Type	Description
`unit`	"seconds" \| "minutes" \| "hours" \| "days" \| "weeks"	Unit of duration.
`value`	number	Number of seconds, minutes, hours, days, or weeks to delay the workflow.

An example duration

Let's say you want to express a duration that delays for 15 minutes, here's how you structure that:

You then reference that as data.delayDuration in the delay step configuration.

A window rule determines a dynamic interval for when the delay should close. It allows you to express rules like "delay until Monday at 9am".

The window rule will always be evaluated in the recipient's timezone (when set) and will fall back to the account default timezone, or "Etc/UTC".

Window rule properties

Variable	Type	Description
`frequency`	"hourly" \| "daily" \| "weekly" \| "monthly"	The frequency at which the window rule should evaluate.
`days`	DaysOfWeek[], "weekdays", "weekends" (optional)	The specific days the rule is valid on.
`hours`	number (optional)	The hour at which the rule should evaluate. Defaults to 0.
`minutes`	number (optional)	The minute at which the rule should evaluate. Must be one of: 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55. Defaults to 0.
`day_of_month`	number (optional)	When frequency is "monthly", set this value to specify the day of the month when the rule executes. If omitted, the rule uses the day of the month on which the delay window opened and executes at the next occurrence of the configured time.

Example window rule

Let's say you want to express setting a window rule for delaying until Monday at 9am, here's how you might structure that on your recipient:

Now you can set the delay window key to recipient.delayUntil to reference this window rule.

Wait until a relative timestamp

You can use our relative delay to wait some time before or after a timestamp that you provide in your workflow payload. This computes a delay time for a fixed interval relative to a dynamic timestamp.

Relative delay functions are helpful for various scenarios, including:

Appointment reminders: send a notification one day before an appointment time
Follow-up reminders: send a follow-up message two hours after an event

When configuring a relative delay, you'll specify:

A fixed delay interval (provided by you in the workflow editor)
Whether the delay should occur before or after the dynamic timestamp
The key for the dynamic timestamp (which can come from your trigger data, recipient data, or other sources)

As in the dynamic delay section above, the specified key must be available to be resolved. If the key is missing or resolves to an invalid value, a corresponding error will be logged on the workflow run, and the delay will be skipped. If the computed time is more than 365 days after the delay step runs, Knock logs an error and halts the workflow run. For example, a delay set to end one day before a timestamp 400 days out resolves to 399 days and halts the run.

Wait until a time window

A time window delay holds the workflow until the recipient is inside a weekly schedule you define, such as business hours, and then continues to the next step. Use it when the rest of the workflow should only run at a reasonable time for the recipient.

For example, say the schedule is open Monday through Friday from 9am to 6pm. A workflow run that reaches the delay on a Saturday waits until Monday at 9am, then continues. A run that reaches the delay at 2pm on a Tuesday is already inside the schedule, so it continues without waiting.

To set one up, choose Window as the delay type on the delay step, then mark each day of the week as open or closed. A day can stay open all day or between a start and end time, set in 15 minute increments. At least one day must be open.

Knock evaluates the delay window in the recipient's timezone when one is set, and falls back to the account default timezone, then Etc/UTC. A recipient in New York and a recipient in London each wait for 9am in their own timezone.

A few things to keep in mind:

Editing the schedule doesn't move waiting runs. A run that is already paused on the step keeps the time it was given. Cancel the workflow run if you need to stop it.
Time window delays are different from send windows. A time window delay pauses the whole workflow. A channel step send window only holds that channel's message while the workflow run proceeds. If a later channel step has its own send windows and they're closed when a delay ends, that step's message will wait until its send window opens.
The Window option is not a window rule. A window rule is a dynamic delay value, such as "delay until Monday at 9am", that you pass in your trigger data.

Setting the workflow version mode

A delay step can continue on the latest workflow version or stay pinned to the version that started the delay. New delay steps default to latest mode.

Set this on the delay step with the "Continue on latest version" toggle. You can also set workflow_version_mode to latest or pinned when you manage the workflow through the Management API or CLI.

Latest (default)

In latest mode, when the delay elapses, Knock continues the workflow on the newest published version that still includes this delay step with latest mode enabled. That version is either the one that started the run, or a version published after it. Template and step changes on that version are used for the continuation.

Use latest mode for long delays, such as onboarding or reminders, so template and step edits published during the delay apply when the run resumes.

Pinned

Pinned mode ties the delay to the workflow version that started the run. When the delay elapses, the run continues on that version, using the templates and steps from that version.

Pinned is an advanced option. Use it when a delayed run should stay on the version that started it.

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

If you've enabled environments, you'll often 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 on the Variables page under the Account section of your account settings with a relative duration as JSON ({ "unit": "seconds", "value": 30 }) and a name of delayDuration. You can set per-environment values to specify a shorter or longer window as needed
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 use the workflow cancellation API to cancel a delayed workflow. You must use a unique cancellation key to cancel a previously triggered workflow run.

A delay step can pause a workflow run for at most 365 days, measured from when the step runs.

Knock rejects a fixed interval longer than 365 days when you configure the workflow. When a dynamic or relative delay resolves to more than 365 days out, Knock logs an error on the workflow run and halts the run instead of skipping the delay.

To send a notification further out, create a one-time schedule with scheduled_at set to the send time, or trigger the workflow closer to the date.

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

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.

Yes. Recipient properties and preferences are re-read from your Knock environment each time a step executes, so a delayed run renders with the recipient data that's current when the delay ends.

Subscription properties behave differently. Knock resolves the properties on a subscription at the point of fan-out and holds them for the life of the run, so an update you make to a subscription during a delay will not appear under recipient.subscription when the run resumes. See the FAQ about subscription properties on paused workflow runs for more detail.

It depends on the delay step's workflow version mode.

In latest mode (the default for new delay steps), when the delay elapses, Knock continues the workflow on the newest published version that still includes this delay step with latest mode enabled. That version is either the one that started the run, or a version published after it. Template and step changes on that version are used for the continuation.

In pinned mode, the run stays on the workflow version that was current when the run was triggered. The run uses the templates and steps from that version. To stop a delayed run after you update the workflow, use the workflow cancellation API.

Pinned mode is an advanced option. Use it when a delayed run should stay on the workflow version that started it.

For long delays, keep latest mode enabled so template and step edits apply when the run resumes.