KnockDocs

API reference

Overview

The Knock API enables you to add a complete notification engine to your product. This API provides programmatic access to integrating Knock via a REST-ful API.

Client libraries

Knock offers native SDKs in several popular programming languages:

API keys

Knock authenticates your API requests using your account's API keys. API requests made without authentication or using an incorrect key will return a 401 error. Requests using a valid key but with insufficient permissions will return a 403 error.

You can view and manage your API keys in the Developer Dashboard. There are two types of API keys:

  • Publishable keys are only meant to identify your account with Knock. They aren't secret, and can safely be made public in any of your client-side code. Publishable keys are prefixed with pk_*.

  • Secret keys can perform any API request to Knock, they should be kept secure and private! Be sure to prevent secret keys from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. Secret keys are prefixed with sk_*.

Each Environment in your account has both a publishable and secret key pair. API requests will be scoped to the provided key's Environment.

Authentication

You must pass your API key to Knock as a Bearer token using the following header:

Errors

Knock uses standard HTTP response codes to indicate the success or failure of your API requests.

  • 2xx - Indicates success.
  • 4xx - Indicates an error, normally due to error caused by incorrect or missing request information (e.g. providing an incorrect API key).
  • 5xx - Indicates a Knock server error.

Users

A user represents an individual who may need to receive a notification from Knock. They are always referenced by your internal identifier.

Attributes

idstringUnique identifier for the user
namestringThe full name of the user
emailstringThe email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
*key-value pairsAny custom properties
Endpoints
PUT/users/:user_id
GET/users/:user_id
DELETE/users/:user_id

Identify a user

Identifying a user will create or update a user in Knock, merging the properties given with what we currently have set on the user (if any).

Endpoint

PUT/users/:user_id

Path parameters

idstringUnique identifier of the user

Body parameters

namestringThe name of the user
emailstringThe email of the user
avatarstring (optional)A URL for the avatar of the user
phone_numberstring (optional)The phone number of the user to use with SMS channels
*key-value pairsAny custom properties

Returns

A User.

Get a user

Retrieve a user by their ID, including all properties previously set.

Endpoint

GET/users/:user_id

Path parameters

idstringUnique identifier of the user

Returns

A User.

Workflows

A Workflow orchestrates the delivery of messages to your end users. When you configure a workflow you'll determine which channels its messages should route to, what those messages should look like on each channel, as well as any functionsโ€”batch, throttle, digestโ€”you want applied to the messages prior to delivery. A workflow is triggered by a notify call, usually when something occurs in your product that you want your users to know about (e.g. a new comment.)

Endpoints
POST/workflows/:key/trigger
POST/workflows/:key/cancel

Triggering a workflow (notify)

A notify calls a workflow created via the Knock dashboard.

Endpoint

POST/workflows/:key/trigger

Path parameters

keystringThe key of the workflow to call

Body parameters

recipientsstring[]A list of user ids of who should be notified
actorstringThe id of the actor who performed the action associated
cancellation_keystring (optional)The key to use for canceling the workflow
tenantstring (optional)The id of the tenant that this workflow run should be associated with
datadictionaryA set of key value pairs to pass to the notify

Returns

workflow_run_idstringA unique UUID of this workflow run

Canceling workflows

Cancel a delayed workflow for one or more recipients.

Endpoint

POST/workflows/:key/cancel

Path parameters

keystringThe key of the workflow

Body parameters

cancellation_keystringThe cancellation key unique to the notify
recipientsstring[]An optional list of user ids to cancel the workflow for

Returns

204, with empty content.

Preferences

A preference determines whether a user should receive a particular type of notification. By default all preferences are opted in unless a preference explicitly opts the user out of the notification.

Preferences are always executed as channel types and then workflows. That means that if a channel type is set to opt out the user then no notifications will be sent on that channel.

Attributes

idstringUnique identifier for the preference set
workflowsobjectA set of preferences for workflows, each can resolve to a boolean or to a set of channel types
channel_typesobjectA set of preferences for channel types
Endpoints
GET/users/:user_id/preferences
GET/users/:user_id/preferences/:id
PUT/users/:user_id/preferences/:id
PUT/users/:user_id/preferences/:id/channel_types
PUT/users/:user_id/preferences/:id/channel_types/:type
PUT/users/:user_id/preferences/:id/workflows
PUT/users/:user_id/preferences/:id/workflows/:key

Get a preference set

Retrieve a user's preference object. Will always return an empty preference object, even if it does not currently exist for the user.

Endpoint

GET/users/:user_id/preferences/:id

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Response

Returns a PreferenceSet.

Set preferences

Sets preferences within the given preference set. This is a destructive operation and will replace any existing preferences with the preferences given.

Endpoint

PUT/users/:user_id/preferences/:id

Path parameters

user_idstringUnique identifier for the user
idstringUnique identifier for the preference set

Body parameters

channel_typesobjectA set of channel type preferences to set
workflowsobjectA set of workflow preferences, can be a boolean or an object containing channel type preferences

Response

Returns a PreferenceSet.

Channel data

Channel data is user and channel specific information that's needed in order 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.

Attributes

channel_idstringThe UUID of the channel this data belongs to
dataobjectThe provider specific channel data
Endpoints
GET/users/:user_id/channel_data/:channel_id
PUT/users/:user_id/channel_data/:channel_id

Getting channel data

Retrieves the channel data for the user on the channel specified

Endpoint

GET/users/:user_id/channel_data/:channel_id

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the channel to lookup

Returns

  • 200 with a ChannelData object (when found)
  • 404 when not found

Setting channel data

Sets the channel data for the user and the channel specified

Endpoint

PUT/users/:user_id/channel_data/:channel_id

Path parameters

user_idstringThe id of the user to lookup
channel_idstringThe id of the channel to lookup

Body parameters

dataobjectThe data to set for this channel, shape of the payload varies depending on the channel

Returns

  • 200 with a ChannelData object (when set)
  • 400 when the channel specified cannot be found
  • 422 with errors when the data is incorrectly shaped

In-app notification feeds

A feed exposes the messages delivered to an in-app feed channel, formatted specially to be consumed in a notification feed.

A feed will always return a list of FeedItems, which are pointers to a message delivered and contain all of the information needed in order to render an item within a notification feed.

Note: feeds are a specialized form of messages that are designed purely for in-app rendering, and as such return information that is required on the client to do so

Attributes

entriesFeedItem[]An ordered list of feed items (most recent first)
page_infoPageInfoPagination information for the items returned
varsobjectEnvironment specific account variables
metaFeedMetadataInformation about the total unread and unseen items
Endpoints
GET/users/:user_id/feeds/:feed_id

Get feed for user

Retrieves a feed of items for a given user_id on the given feed_id.

Note: if you're making this call from a client-side environment you should be using your publishable key along with a user token to make this request

Endpoint

GET/users/:user_id/feeds/:feed_id

Path parameters

user_idstringThe ID of the user
feed_idstringThe ID of the feed (the channel ID)

Query parameters

page_sizenumberThe total number to retrieve per page (defaults to 50)
afterstringThe cursor to retrieve items after (hint: use the `__cursor` field)
beforestringThe cursor to retrieve items before (hint: use the `__cursor` field)
sourcestring (optional)Limits the feed to only items of the source workflow
tenantstring (optional)Limits the feed to only display items with the corresponding tenant, or where the tenant is empty
statusstring (optional)One of `unread`, `unseen`, `all`

Returns

A feed response.

Messages

A message is a notification delivered on a particular channel to a user.

Attributes

idstringThe unique ID of this message
channel_idstringThe ID of the channel for where this message was delivered
recipientstringThe ID of the user who received the message
workflowstringThe key of the workflow that this message was generated from
tenantstringThe ID of the tenant that this message belongs to
statusstringOne of `queued`, `sent`, `delivered`, `undelivered`, `seen`, `unseen`
read_atstring (optional)When the message was last read
seen_atstring (optional)When the message was last seen
archived_atstring (optional)When the message was archived
Endpoints
PUT/messages/:id/:status
DELETE/messages/:id/:status
POST/messages/batch/:status
POST/channels/:id/messages/bulk/:status

Updating a message status

Marks the given message as the status, recording an event in the process.

Endpoint

PUT/messages/:id/:status

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `archived`

Returns

A Message.

Undoing a message status change

Un-marks the given message as the status, recording an event in the process.

Endpoint

DELETE/messages/:id/:status

Path parameters

idstringThe ID of the message
statusenumOne of `seen`, `read`, `archived`

Returns

A Message.

Batch changing message statuses

Multiple messages can be changed at once using the batch API, where all message ids given in will have their statuses changed.

Endpoint

POST/messages/batch/:status

Path parameters

statusenumOne of `seen`, `read`, `archived` or `unseen`, `unread`, `unarchived`

Body parameters

message_idsstring[]A list of one or more message IDs

Returns

A list of Messages that were mutated during the call.

Bulk changing message statuses in a channel

The bulk change endpoint allows you to modify all, or a subset of messages for a given channel via an asyncronous job. The messages to be modified can be filtered using the properties listed below, and this operation will always return a BulkOperation which allows you to track the status of the job.

Endpoint

POST/channels/:id/messages/bulk/:status

Path parameters

idstringThe ID of a channel that you wish to modify messages under
statusenumOne of `seen`, `read`, `archive` or `unseen`, `unread`, `unarchive`

Body parameters

user_idsstring[]Scope the bulk update to one or more users (optional)
older_thanstringAn ISO-8601 timestamp to find messages created before (optional)
newer_thanstringAn ISO-8601 timestamp to find messages created after (optional)
delivery_statusenumLimit messages to one of `queued`, `sent`, `delivered`, `undelivered` (optional)
engagement_statusenumLimit messages to one of `seen`, `unseen`, `read`, `unread`, `archived`, `unarchived` (optional)

Returns

A BulkOperation

Bulk operations

A bulk operation represents a set of changes that are to be performed across 0 or more records. The bulk operation resource represents the state of the operation, including recording the number of rows that have been modified during the operation.

Please note here: the estimated_total_rows field may have a different value to the processed_rows field due to the asyncronous nature of the operation. If you wish to pin this job to a specific point in time, you can initiate it with a date filter (like older_than).

Attributes

idstringThe unique ID of this bulk operation
namestringThe type of operation being performed
estimated_total_rowsintegerAn approximation of the number of rows that will be mutated in this operation
processed_rowsintegerThe number of the rows that have been mutated in this operation
statusenumOne of `queued`, `processing`, `completed`, `failed`
started_atstringAn ISO-8601 datetime string for when the operation started processing
completed_atstringAn ISO-8601 datetime string for when the operation completed processing
failed_atstringAn ISO-8601 datetime string for when the operation failed processing
Endpoints
GET/bulk_operations/:id

Retrieve a bulk operation

Retrieve the bulk operation, revealing the current status and the number of rows processed. You can poll this endpoint to understand when a bulk operation has finished executing (either completed, or failed).

Endpoint

GET/bulk_operations/:id

Path parameters

idstringThe ID of a bulk operation to retrieve

Returns

A BulkOperation