Docs
/
/

Workflows Management API reference

Complete reference documentation for the Workflows resource.

Workflows

#

To define a logical flow for your notifications, you create a workflow consisting of steps. Workflow steps can be functions or channels, and can have conditional logic that determines whether to execute that step when the workflow is triggered.

You can retrieve, update, or create a workflow as well as list all workflows in a given environment. Workflows are identified by their unique workflow key.

List workflows

#

Returns a paginated list of workflows available in a given environment. The workflows are returned alphabetically by key.

Endpoint

GET/v1/workflows

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

after
string

The cursor to fetch entries after.

before
string

The cursor to fetch entries before.

limit
integer

The number of entries to fetch per-page.

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changes
boolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

PaginatedWorkflowResponse

A paginated list of Workflow. Contains a list of entries and page information.

entries

A list of entries.

active
boolean
Required

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)
Required

The timestamp of when the workflow was created. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string
Required

The slug of the environment in which the workflow exists. (read-only).

key
string
Required

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string
Required

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string
Required

The SHA hash of the workflow data. (read-only).

stepsRequired

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)
Required

The timestamp of when the workflow was last updated. (read-only).

valid
boolean
Required

Whether the workflow and its steps are in a valid state. (read-only).

page_info

The information about a paginated result.

after
string

The cursor to fetch entries after. Will only be present if there are more entries to fetch.

before
string

The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.

page_size
integer

The number of entries to fetch per-page.

Get a workflow

#

Retrieve a workflow by its key in a given environment.

Endpoint

GET/v1/workflows/{workflow_key}

Path parameters

workflow_key
string

The key of the workflow to retrieve.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

hide_uncommitted_changes
boolean

Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.

Returns

ShowWorkflowResponse

A workflow object.

active
boolean

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)

The timestamp of when the workflow was created. (read-only).

created_by
WorkflowUserInfo

Information about the user who created the workflow. Only included in detailed views. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the workflow exists. (read-only).

key
string

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string

The SHA hash of the workflow data. (read-only).

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)

The timestamp of when the workflow was last updated. (read-only).

updated_by
WorkflowUserInfo

Information about the user who last updated the workflow. Only included in detailed views. (read-only).

valid
boolean

Whether the workflow and its steps are in a valid state. (read-only).

Upsert a workflow

#

Updates a workflow of a given key, or creates a new one if it does not yet exist.

Note: this endpoint only operates on workflows in the development environment.

Endpoint

PUT/v1/workflows/{workflow_key}

Path parameters

workflow_key
string

The key of the workflow.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

annotate
boolean

Whether to annotate the resource. Only used in the Knock CLI.

commit
boolean

Whether to commit the resource at the same time as modifying it.

commit_message
string

The message to commit the resource with, only used if commit is true.

Request body

workflow
WorkflowRequest

A workflow request for upserting a workflow.

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

name
string
Required

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

stepsRequired

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the workflow key.

workflow

A workflow object. Read more in the docs.

active
boolean

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)

The timestamp of when the workflow was created. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the workflow exists. (read-only).

key
string

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string

The SHA hash of the workflow data. (read-only).

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)

The timestamp of when the workflow was last updated. (read-only).

valid
boolean

Whether the workflow and its steps are in a valid state. (read-only).

Activate a workflow

#

Activates (or deactivates) a workflow in a given environment. Read more in the docs.

Note: This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.

Endpoint

PUT/v1/workflows/{workflow_key}/activate

Path parameters

workflow_key
string

The key of the workflow.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

Request body

status
boolean
Required

Whether to activate or deactivate the workflow. Set to true by default, which will activate the workflow.

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the workflow key.

workflow

A workflow object. Read more in the docs.

active
boolean

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)

The timestamp of when the workflow was created. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the workflow exists. (read-only).

key
string

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string

The SHA hash of the workflow data. (read-only).

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)

The timestamp of when the workflow was last updated. (read-only).

valid
boolean

Whether the workflow and its steps are in a valid state. (read-only).

Run a workflow

#

Runs the latest version of a committed workflow in a given environment using the params provided.

Endpoint

PUT/v1/workflows/{workflow_key}/run

Path parameters

workflow_key
string

The key of the workflow.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

Request body

actor
RecipientReference

The actor to reference in the the workflow run.

cancellation_key
string

A key to cancel the workflow run.

data
object(any)

A map of data to be used in the workflow run. The structure should conform to the workflow's trigger_data_json_schema if one is defined. Available in templates as {{ data.field_name }}. See trigger data validation docs.

recipients
RecipientReference[]
Required

A list of recipients to run the workflow for.

tenant
string

The tenant to associate the workflow run with. Must not contain whitespace.

Returns

RunWorkflowResponse

A response to a run workflow request.

workflow_run_id
string(uuid)

The ID of the workflow run.

Validate a workflow

#

Validates a workflow payload without persisting it. Some read-only fields will be empty as they are generated by the system when persisted.

Note: Validating a workflow is only done in the development environment context.

Endpoint

PUT/v1/workflows/{workflow_key}/validate

Path parameters

workflow_key
string

The key of the workflow.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

Request body

workflow
WorkflowRequest

A workflow request for upserting a workflow.

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

name
string
Required

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

stepsRequired

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant

Returns

WrappedWorkflowResponse

Wraps the Workflow response under the workflow key.

workflow

A workflow object. Read more in the docs.

active
boolean

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)

The timestamp of when the workflow was created. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the workflow exists. (read-only).

key
string

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string

The SHA hash of the workflow data. (read-only).

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)

The timestamp of when the workflow was last updated. (read-only).

valid
boolean

Whether the workflow and its steps are in a valid state. (read-only).

Steps

#

Methods that operate on the individual steps within a workflow. Steps are referenced by their ref, which is unique within a workflow.

Preview a workflow template

#

Generates a rendered template for a given channel step in a workflow.

Endpoint

POST/v1/workflows/{workflow_key}/steps/{step_ref}/preview_template

Path parameters

workflow_key
string

The key of the workflow.

step_ref
string

The reference key of the channel step in the workflow to preview.

Query parameters

environment
string

The environment slug.

branch
string

The slug of a branch to use. This option can only be used when environment is "development".

Request body

actor
RecipientReference

The actor to reference in the the workflow run.

data
object(any)

The data to pass to the workflow template for rendering.

recipient
2 possible types
Required

A recipient reference, used when referencing a recipient by either their ID (for a user), or by a reference for an object.

tenant
string

The tenant to associate the workflow with. Must not contain whitespace.

Returns

PreviewWorkflowTemplateResponse

A response to a preview workflow template request.

content_type
enum(string)

The content type of the preview.

emailin_app_feedpushchatsmshttp
result
enum(string)

The result of the preview.

successerror
template
6 possible types

The rendered template, ready to be previewed.

Condition

#

A condition to be evaluated.

Attributes

argument
string

The argument to be evaluated. Arguments can be either static values or dynamic properties. Static values will always be JSON decoded so will support strings, lists, objects, numbers, and booleans. Dynamic values should be path expressions.

operator
enum(string)

The operator to use in the evaluation of the condition.

equal_tonot_equal_togreater_thanless_thangreater_than_or_equal_toless_than_or_equal_tocontainsnot_containscontains_allnot_contains_allis_timestamp_beforeis_timestamp_afteris_timestamp_before_dateis_timestamp_after_dateis_timestamp_betweenemptynot_emptyis_timestampis_audience_memberis_not_audience_member
variable
string

The variable to be evaluated. Variables can be either static values or dynamic properties. Static values will always be JSON decoded so will support strings, lists, objects, numbers, and booleans. Dynamic values should be path expressions.

ConditionGroup

#

A group of conditions to be evaluated.

Attributes

ConditionGroup
2 possible types

A group of conditions to be evaluated.

Duration

#

A duration of time, represented as a unit and a value.

Attributes

unit
enum(string)

The unit of time.

minuteshoursdaysweeksmonths
value
integer

The value of the duration.

SendWindow

#

A send window time for a notification. Describes a single day.

Attributes

day
enum(string)

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

Workflow

#

A workflow object. Read more in the docs.

Attributes

active
boolean

Whether the workflow is active in the current environment. (read-only).

categories
string[]

A list of categories that the workflow belongs to.

conditions

A conditions object that describes one or more conditions to be met for the workflow to be executed. (optional).

created_at
string(date-time)

The timestamp of when the workflow was created. (read-only).

deleted_at
string(date-time)

The timestamp of when the workflow was deleted. (read-only).

description
string

An arbitrary string attached to a workflow object. Useful for adding notes about the workflow for internal purposes. Maximum of 280 characters allowed.

environment
string

The slug of the environment in which the workflow exists. (read-only).

key
string

The unique key string for the workflow object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.

name
string

A name for the workflow. Must be at maximum 255 characters in length.

settings
object

A map of workflow settings.

is_commercial
boolean

Whether the workflow is commercial. Defaults to false.

override_preferences
boolean

Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.

sha
string

The SHA hash of the workflow data. (read-only).

A list of workflow step objects in the workflow.

trigger_data_json_schema
object(any)

A JSON schema for the expected structure of the workflow trigger's data payload (available in templates as {{ data.field_name }}). Used to validate trigger requests. Read more in the docs.

trigger_frequency
enum(string)

The frequency at which the workflow should be triggered. One of: once_per_recipient, once_per_recipient_per_tenant, every_trigger. Defaults to every_trigger. Read more in docs.

every_triggeronce_per_recipientonce_per_recipient_per_tenant
updated_at
string(date-time)

The timestamp of when the workflow was last updated. (read-only).

valid
boolean

Whether the workflow and its steps are in a valid state. (read-only).

WorkflowStep

#

A step within a workflow. Each workflow step, regardless of its type, share a common set of core attributes (type, ref, name, description, conditions).

Attributes

WorkflowStep
12 possible types

A step within a workflow. Each workflow step, regardless of its type, share a common set of core attributes (type, ref, name, description, conditions).

WorkflowBatchStep

#

A batch function step. Read more in the docs.

Attributes

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

settings
object

The settings for the batch step.

batch_execution_mode
enum(string)

The execution mode of the batch step. One of: accumulate or flush_leading. When set to flush_leading, the first item in the batch will be executed immediately, and the rest will be batched. See these docs for more information.

accumulateflush_leading
batch_items_max_limit
integer

The maximum number of batch items allowed in a batch. Between: 2 and 1000.

batch_items_render_limit
integer

The maximum number of batch items allowed to be rendered into a template. Between: 1 and 100. Defaults to 10.

batch_key
string

The data property to use to batch notifications per recipient.

batch_order
enum(string)

The order describing whether to return the first or last ten batch items in the activities variable. One of: asc or desc.

ascdesc
batch_until_field_path
string

The data path to resolve the batch window. The resolved value must be an ISO-8601 timestamp.

batch_window

The window of time to collect events in the batch.

batch_window_extension_limit

A duration object that describes the maximum duration a batch window can be extended to from opening when using a sliding batch window.

batch_window_type
enum(string)

The type of the batch window used. One of: fixed or sliding.

fixedsliding
type
enum(string)

The type of the workflow step.

batch

WorkflowBranchStep

#

A branch function step. Read more in the docs.

Attributes

branches
WorkflowBranchStepBranch[]

A list of workflow branches to be evaluated.

conditions

A set of conditions to be evaluated for this branch.

name
string

The name of the branch.

A list of steps that will be executed if the branch is chosen.

terminates
boolean

If the workflow should halt at the end of the branch. Defaults to false if not provided.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

type
enum(string)

The type of step.

branch

WorkflowChatStep

#

A chat step within a workflow. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_overrides

A map of channel overrides for the channel step.

channel_type
enum(string)

The type of the channel step. Always chat for chat steps.

chat
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

template

A chat template.

json_body
string

A JSON template for the chat notification message payload. Only present if not using the markdown body.

markdown_body
string

The markdown body of the chat template.

summary
string

The summary of the chat template. Used by some chat apps in their push notifications.

type
enum(string)

The type of the workflow step.

channel

WorkflowInAppFeedStep

#

An in-app feed step within a workflow. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_overrides

A map of channel overrides for the channel step.

channel_type
enum(string)

The type of the channel step. Always in_app_feed for in-app feed steps.

in_app_feed
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

An in-app feed template.

action_buttons
object[]

The action buttons of the in-app feed message.

action
string
Required

The URI for this action.

label
string
Required

The label of the action button.

action_url
string

The URL to navigate to when the in-app feed is tapped. Can be omitted for multi-action templates, where the action buttons will be used instead.

markdown_body
string

The markdown body of the in-app feed.

type
enum(string)

The type of the workflow step.

channel

WorkflowEmailStep

#

An email step within a workflow. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_overrides

A map of channel overrides for the channel step.

channel_type
enum(string)

The category of channel for this step. Always email for email steps. This identifies the type of notification (email, sms, push, etc.) while channel_key specifies which configured provider instance to use.

email
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

An email message template.

html_body
string

An HTML template for the email body. Required if visual_blocks is not provided. Only one of html_body or visual_blocks should be set. Supports Liquid templating with variables like {{ recipient.name }}, {{ actor.name }}, {{ vars.app_name }}, {{ data.custom_field }}, and {{ tenant.name }}. See the template variables reference for available variables.

settings
EmailTemplateSettings

The settings for the email template. Must be supplied with at least layout_key.

attachment_key
string

The object path in the workflow trigger's data payload to resolve attachments.Defaults to attachments.

layout_key
string

The key of the email layout that wraps the email template. When omitted, the email template will need to define the <html> structure.

pre_content
string

A liquid template that will be injected into the email layout above the message template content. Useful for setting variables that should be available to the email layout.

subject
string

The subject of the email. Supports Liquid templating with variables like {{ recipient.name }}, {{ actor.name }}, {{ vars.app_name }}, {{ data.custom_field }}, and {{ tenant.name }}. See the template variables reference for available variables.

text_body
string

A text template for the email body. When omitted, the email template will be autogenerated from the html_body or visual_blocks.

visual_blocks
object[]

The visual blocks that make up the email template. Required if html_body is not provided. Only one of html_body or visual_blocks should be set.

type
enum(string)

The type of the workflow step.

channel

WorkflowPushStep

#

A push step within a workflow. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_overrides

A map of channel overrides for the channel step.

channel_type
enum(string)

The type of the channel step. Always push for push steps.

push
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

template

A push notification template.

settings
object

The settings for the push template.

delivery_type
enum(string)
Required

The delivery type of the push notification. Set as silent to send a data-only notification. When set to silent, no body will be sent.

silentcontent
payload_overrides
string

A JSON object that overrides the payload sent to the push provider.

text_body
string

The body of the push notification.

title
string

The title of the push notification.

type
enum(string)

The type of the workflow step.

channel

WorkflowSmsStep

#

A SMS step within a workflow. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_overrides

A map of channel overrides for the channel step.

channel_type
enum(string)

The type of the channel step. Always sms for SMS steps.

sms
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

template

An SMS template.

settings
object

The settings for the SMS template. Can be omitted.

text_body
string

The message of the SMS.

type
enum(string)

The type of the workflow step.

channel

WorkflowWebhookStep

#

A webhook step within a workflow to send an HTTP request to a generic channel. Read more in the docs.

Attributes

channel_group_key
string

The key of the channel group to which the channel step will be sending a notification. Either channel_key or channel_group_key must be provided, but not both.

channel_key
string

The key of a specific configured channel instance (e.g., 'knock-email', 'postmark', 'sendgrid-marketing') to send the notification through. Either channel_key or channel_group_key must be provided, but not both.

channel_type
enum(string)

The type of the channel step. Always http for webhook steps.

http
conditions

A set of conditions to be evaluated for this channel step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

send_windows

A list of send window objects. Must include one send window object per day of the week.

day
enum(string)
Required

The day of the week.

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
from
string(time)

The start time of the send window.

type
enum(string)
Required

The type of send window.

senddo_not_send
until
string(time)

The end time of the send window.

A webhook template. By default, a webhook step will use the request settings you configured in your webhook channel. You can override this as you see fit on a per-step basis.

body
string

The body of the request. Only used for POST or PUT requests.

headers
object[]

A list of key-value pairs for the request headers. Each object should contain key and value fields with string values.

key
string
Required

The key of the header.

value
string
Required

The value of the header.

method
enum(string)

The HTTP method of the webhook.

getpostputdeletepatch
query_params
object[]

A list of key-value pairs for the request query params. Each object should contain key and value fields with string values.

key
string
Required

The key of the query param.

value
string
Required

The value of the query param.

url
string

The URL of the webhook.

type
enum(string)

The type of the workflow step.

channel

WorkflowDelayStep

#

A delay function step. Read more in the docs.

Attributes

conditions

A set of conditions to be evaluated for this delay step.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

settings
object

The settings for the delay step. Both fields can be set to compute a delay where delay_for is an offset from the delay_until_field_path.

delay_for

A duration object that describes how long to wait before proceeding to the next step.

delay_until_field_path
string

When set will use the path to resolve the delay into a timestamp from the property referenced

type
enum(string)

The type of the workflow step.

delay

WorkflowFetchStep

#

A fetch function step. Retrieves data from an external source and merges it into the workflow's data scope for use in later steps. Read more in the docs.

Attributes

conditions

A conditions object that describes one or more conditions to be met in order for the step to be executed.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

A request template for a fetch function step.

body
string

The body of the request. Only used for POST or PUT requests.

headers
2 possible types

The headers of the request. Can be a template string or a list of key-value pairs.

method
enum(string)

The HTTP method of the request.

getpostputdeletepatch
query_params
2 possible types

The query params of the request. Can be a template string or a list of key-value pairs.

url
string

The URL of the request.

type
enum(string)

The type of the workflow step.

http_fetch

WorkflowThrottleStep

#

A throttle function step. Read more in the docs.

Attributes

conditions

A conditions object that describes one or more conditions to be met in order for the step to be executed.

description
string

An arbitrary string attached to a workflow step. Useful for adding notes about the workflow for internal purposes.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

settings
object

The settings for the throttle step.

throttle_key
string

The data property to use to throttle notifications per recipient.

throttle_limit
integer

The maximum number of workflows to allow within the duration window. Defaults to 1.

throttle_window

The duration of the throttle window.

throttle_window_field_path
string

The data path to resolve a dynamic throttle window. The resolved value must be an ISO-8601 timestamp. See more in the docs.

type
enum(string)

The type of the workflow step.

throttle

WorkflowTriggerWorkflowStep

#

A workflow trigger function step. Read more in the docs.

Attributes

conditions

A set of conditions to be evaluated for this trigger workflow step.

description
string

A description for the workflow step.

name
string

A name for the workflow step.

ref
string

The reference key of the workflow step. Must be unique per workflow.

settings
object

The settings for the workflow trigger workflow step.

actor
string

The actor to trigger the workflow with. Supports liquid.

cancellation_key
string

The cancellation key to trigger the workflow with. Supports liquid.

data
string

The data to be supplied to the workflow. Supports liquid.

recipients
string

The recipients or recipient to trigger the workflow for. Supports liquid.

tenant
string

The tenant to trigger the workflow with. Supports liquid.

workflow_key
string

The key of the workflow to trigger. Supports liquid.

type
enum(string)

The type of the workflow step.

trigger_workflow
New chat