Docs

Contact support Log in Get started

Client libraries

Batch rate limits

Idempotent requests

Trigger data filtering

Common error codes

Object definitions

Object definitions

Object definitions

RecipientRequest

RecipientReference

Delete a tenant

Bulk delete tenants

Bulk set tenants

InlineTenantRequest

Get bulk operation

Process a Census RPC request

Process a Hightouch RPC request

Trigger workflow

Cancel workflow

Create schedules

Update schedules

Delete schedules

Create schedules in bulk

ScheduleRepeatRule

Bulk update message statuses for channel

Get started Log in Contact support

Developer tools

Recipients API reference

Complete reference documentation for the Recipients resource.

Recipients

#

A Recipient represents a person or a non-user entity from your system, represented in Knock. They are most commonly the recipient of a notification, but can also be used to denote an actor that a notification is sent on behalf of.

Subscriptions

#

Subscriptions express the relationship between a Recipient (the subscriber) and an Object. Subscribers are notified when the object that they are subscribed to is a recipient on a workflow trigger request.

Subscription

#

A subscription object.

Attributes

__typename

string

The typename of the schema.

inserted_at

string(date-time)

Timestamp when the resource was created.

object

A custom Object entity which belongs to a collection.

__typename

string

The typename of the schema.

collection

string

The collection this object belongs to.

created_at

string(date-time)

Timestamp when the resource was created.

id

string

Unique identifier for the object.

properties

object(any)

The custom properties associated with the object.

updated_at

string(date-time)

The timestamp when the resource was last updated.

properties

object(any)

The custom properties associated with the subscription relationship.

recipient

2 possible types

A recipient of a notification, which is either a user or an object.

updated_at

string(date-time)

The timestamp when the resource was last updated.

Preferences

#

Preferences determine whether a recipient should receive a particular type of notification. By default all preferences are opted in unless a preference explicitly opts the recipient out of the notification.

The preference set :id can be either "default" or a tenant.id. Learn more about per-tenant preferences.

PreferenceSet

#

A preference set represents a specific set of notification preferences for a recipient. A recipient can have multiple preference sets.

Attributes

categories

PreferenceSetCategories

An object where the key is the category and the values are the preference settings for that category.

channel_types

PreferenceSetChannelTypes

An object where the key is the channel type and the values are the preference settings for that channel type.

channels

PreferenceSetChannels

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribed

boolean

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

id

string

Unique identifier for the preference set.

workflows

PreferenceSetWorkflows

An object where the key is the workflow key and the values are the preference settings for that workflow.

PreferenceSetRequest

#

A request to set a preference set for a recipient.

Attributes

__persistence_strategy__

enum(string)

Controls how the preference set is persisted. 'replace' will completely replace the preference set, 'merge' will merge with existing preferences.

mergereplace

categories

PreferenceSetRequestCategories

An object where the key is the category and the values are the preference settings for that category.

channel_types

PreferenceSetChannelTypes

An object where the key is the channel type and the values are the preference settings for that channel type.

channels

PreferenceSetChannels

An object where the key is the channel ID and the values are the preference settings for that channel ID.

commercial_subscribed

boolean

Whether the recipient is subscribed to commercial communications. When false, the recipient will not receive commercial workflow notifications.

workflows

PreferenceSetRequestWorkflows

An object where the key is the workflow key and the values are the preference settings for that workflow.

InlinePreferenceSetRequest

#

Inline set preferences for a recipient, where the key is the preference set id. Preferences that are set inline will be merged into any existing preferences rather than replacing them.

Attributes

*

object(any)

Any additional custom properties.

PreferenceSetChannelTypes

#

Channel type preferences.

Attributes

chat

2 possible types

Whether the channel type is enabled for the preference set.

email

2 possible types

Whether the channel type is enabled for the preference set.

http

2 possible types

Whether the channel type is enabled for the preference set.

in_app_feed

2 possible types

Whether the channel type is enabled for the preference set.

push

2 possible types

Whether the channel type is enabled for the preference set.

sms

2 possible types

Whether the channel type is enabled for the preference set.

PreferenceSetChannelTypeSetting

#

A set of settings for a channel type. Currently, this can only be a list of conditions to apply.

Attributes

conditions

A list of conditions to apply to a channel type.

argument

string

Required

The argument value to compare against in the condition.

operator

enum(string)

Required

The operator to use in the condition evaluation.

equal_tonot_equal_togreater_thanless_thangreater_than_or_equal_toless_than_or_equal_tocontainsnot_containsemptynot_emptycontains_allis_timestampis_not_timestampis_timestamp_on_or_afteris_timestamp_beforeis_timestamp_on_or_after_dateis_timestamp_before_dateis_timestamp_betweenis_audience_memberis_not_audience_member

variable

string

Required

The variable to be evaluated in the condition.

PreferenceSetChannelSetting

#

A set of settings for a specific channel. Currently, this can only be a list of conditions to apply.

Attributes

conditions

A list of conditions to apply to a specific channel.

argument

string

Required

The argument value to compare against in the condition.

operator

enum(string)

Required

The operator to use in the condition evaluation.

equal_tonot_equal_togreater_thanless_thangreater_than_or_equal_toless_than_or_equal_tocontainsnot_containsemptynot_emptycontains_allis_timestampis_not_timestampis_timestamp_on_or_afteris_timestamp_beforeis_timestamp_on_or_after_dateis_timestamp_before_dateis_timestamp_betweenis_audience_memberis_not_audience_member

variable

string

Required

The variable to be evaluated in the condition.

Channel data

#

Channel data is channel-specific information stored on a Knock user or object that's needed to deliver a notification to an end provider.

For a push channel, this includes device-specific tokens that map the recipient to the device they use, as well as device metadata for supported providers. For chat apps, such as Slack, this includes the access token used to send notifications to a customer's Slack channel.

The shape of the data payload varies depending on the channel type; you can learn more about channel data schemas here.

ChannelData

#

Channel data for a given channel type.

Attributes

__typename

string

The typename of the schema.

channel_id

string(uuid)

The unique identifier for the channel.

data

6 possible types

Channel data for a given channel type.

provider

enum(string)

The type of provider.

push_fcmpush_apnspush_aws_snspush_expopush_one_signalchat_slackchat_ms_teamschat_discordhttp_knock_webhook

ChannelDataRequest

#

A request to set channel data for a type of channel.

Attributes

data

8 possible types

Channel data for a given channel type.

PushChannelDataTokensOnly

#

Push channel data.

Attributes

tokens

string[]

A list of push channel tokens.

PushChannelDataDevicesOnly

#

Push channel data.

Attributes

devices

object[]

A list of devices. Each device contains a token, and optionally a locale and timezone.

locale

string

The locale of the object. Used for message localization.

timezone

string

The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules.

token

string

Required

The device token to send the push notification to.

SlackChannelData

#

Slack channel data.

Attributes

connections

object[]

List of Slack channel connections.

token

SlackChannelDataTokenObject

A Slack connection token.

access_token

string

A Slack access token.

AWSSNSPushChannelDataTargetARNsOnly

#

AWS SNS push channel data.

Attributes

target_arns

string[]

A list of platform endpoint ARNs. See Setting up an Amazon SNS platform endpoint for mobile notifications.

AWSSNSPushChannelDataDevicesOnly

#

AWS SNS push channel data.

Attributes

devices

object[]

A list of devices. Each device contains a target_arn, and optionally a locale and timezone.

locale

string

The locale of the object. Used for message localization.

target_arn

string

Required

The ARN of a platform endpoint associated with a platform application and a device token. See Setting up an Amazon SNS platform endpoint for mobile notifications.

timezone

string

The timezone of the object. Must be a valid tz database time zone string. Used for recurring schedules.

MsTeamsChannelData

#

Microsoft Teams channel data.

Attributes

connections

object[]

List of Microsoft Teams connections.

ms_teams_tenant_id

string(uuid)

Microsoft Teams tenant ID.

DiscordChannelData

#

Discord channel data.

Attributes

connections

object[]

List of Discord channel connections.

OneSignalChannelDataPlayerIdsOnly

#

OneSignal channel data.

Attributes

player_ids

string(uuid)[]

A list of OneSignal player IDs.

InlineChannelDataRequest

#

A request to set channel data for a type of channel inline.

Attributes

*

object(any)

Any additional custom properties.

Recipient

#

A recipient of a notification, which is either a user or an object.

Attributes

Recipient

2 possible types

A recipient of a notification, which is either a user or an object.

RecipientRequest

#

Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a collection property.

Attributes

RecipientRequest

3 possible types

Specifies a recipient in a request. This can either be a user identifier (string), an inline user request (object), or an inline object request, which is determined by the presence of a collection property.

RecipientReference

#

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

Attributes

RecipientReference

2 possible types

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

New chat