Broadcasts Management API reference
Complete reference documentation for the Broadcasts resource.
Broadcasts
#Broadcasts are a way to send one-time, cross-channel notifications to your users through Knock. They use the Knock workflow engine, but are configured in the Knock dashboard to run once.
Send a broadcast
#Sends a broadcast immediately or schedules it to send at a future time.
Endpoint
Path parameters
The key of the broadcast.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
When to send the broadcast. If provided, the broadcast will be scheduled to send at this time. Must be in ISO 8601 UTC format. If not provided, the broadcast will be sent immediately.
Returns
Wraps the Broadcast response under the broadcast key.
A broadcast object.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
Validate a broadcast
#Validates a broadcast payload without persisting it.
Endpoint
Path parameters
The key of the broadcast.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
A broadcast request for upserting a broadcast.
A list of categories that the broadcast belongs to.
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
Returns
Wraps the Broadcast response under the broadcast key.
A broadcast object.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
List broadcasts
#Returns a paginated list of broadcasts available in a given environment. The broadcasts are returned ordered by creation time (newest first).
Endpoint
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A paginated list of Broadcast. Contains a list of entries and page information.
A list of entries.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
Get a broadcast
#Get a broadcast by its key in a given environment.
Endpoint
Path parameters
The key of the broadcast to retrieve.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A broadcast object.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
Upsert a broadcast
#Updates a broadcast of a given key, or creates a new one if it does not yet exist.
Endpoint
Path parameters
The key of the broadcast.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Request body
A broadcast request for upserting a broadcast.
A list of categories that the broadcast belongs to.
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
Returns
Wraps the Broadcast response under the broadcast key.
A broadcast object.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
Cancel a scheduled broadcast
#Cancels sending a scheduled broadcast. The broadcast will return to draft status.
Endpoint
Path parameters
The key of the broadcast.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Returns
Wraps the Broadcast response under the broadcast key.
A broadcast object.
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).
BroadcastRequest
#A broadcast request for upserting a broadcast.
Attributes
A list of categories that the broadcast belongs to.
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
Broadcast
#A broadcast object.
Attributes
The timestamp of when the broadcast was archived.
A list of categories that the broadcast belongs to.
The timestamp of when the broadcast was created. (read-only).
An arbitrary string attached to a broadcast object. Useful for adding notes about the broadcast for internal purposes. Maximum of 280 characters allowed.
The slug of the environment in which the broadcast exists. (read-only).
The unique key string for the broadcast object. Must be at minimum 3 characters and at maximum 255 characters in length. Must be in the format of ^[a-z0-9_-]+$.
A name for the broadcast. Must be at maximum 255 characters in length.
The timestamp of when the broadcast is scheduled to be sent.
The timestamp of when the broadcast was sent. (read-only).
A map of broadcast settings.
Whether the broadcast is commercial. Defaults to true.
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.
The SHA hash of the workflow data. (read-only).
The current status of the broadcast. One of: draft, scheduled, sent.
A list of broadcast step objects in the broadcast. Broadcasts only support channel, branch, and delay steps.
The key of the audience to target for this broadcast.
The timestamp of when the broadcast was last updated. (read-only).
Whether the broadcast and its steps are in a valid state. (read-only).