In-app APIs and real-time service

Learn more about the capabilities of Knock's in-app APIs and real-time services, and how these can power robust in-app notification experiences with little effort.

Knock provides a complete set of APIs to render your in-app notifications with the Knock-powered in-app channel. These APIs cover:

  • Fetching a reverse chronological list of in-app feed messages for a user. (API reference).
  • Retrieving badge count information on the number of seen and unread messages a user has.
  • Handling message engagement statuses to mark messages as seen, read, and archived.
  • Real-time delivery of in-app messages from Knock to your user.

Our client-side SDKs wrap these APIs and provide a convenient way to interact with the Knock APIs.

Security model

Knock's in-app APIs are accessible via our client SDKs, which use your public API key to authenticate. In addition, we support an enhanced security mode that signs a request against the current user and provides an additional authorization mechanism. You can read more in our security documentation.

Real-time delivery

Knock provides a real-time web socket connection for your users to subscribe to new messages being produced on an in-app channel. The events we currently send over the web socket are:

EventDescription
new-messageEmitted when a new message is produced over an in-app channel. Will not contain the full message contents, but will include metadata about the updated badge counts. Might be throttled.

Filtering in-app notifications

It's possible to pass filters to the in-app messages endpoint. This allows you to:

  • Only return in-app messages for a particular tenant
  • Only return archived or unarchived messages
  • Filter messages by the data payload used to trigger the notification

You can see the full set of available filters in the endpoint documentation.

💡
Note: by default all archived messages are excluded from the feed.

Please note, by default all archived messages are not displayed.

In-app API response

FeedMetadata

total_countnumberThe total number of messages the user has for this in-app channel.
unread_countnumberThe total number of unread items the user has on the in-app channel.
unseen_countnumberThe total number of unseen items the user has on the in-app channel.

FeedItem

Requests to the feed endpoint will return an array of FeedItems. Each feed item includes:

idstringA unique identifier for the item.
actorsRecipient[]One or more actors that were attributed to the workflow run.
total_actorsnumberThe total count of unique actors includes across all workflow runs that generated this message.
activitiesActivity[]One or more activities associated with this in-app message. Will only include multiple activities when the message was generated from a batch.
total_activitiesnumberThe total count of workflow runs that generated this message. Will only be > 1 when used with a batch.
activitiesActivity[]One or more activities associated with this in-app message. Will only include multiple activities when the message was generated from a batch.
dataRecord<string, any>The combined workflow run data associated with this message. See below for more information.
blocksContentBlock[]The rendered contents of each feed item. See below for more information.
sourceWorkflowSourceThe key, version_id, and categories of the workflow that generated this in-app message.
tenantstringAn optional tenant identifier that was set in the workflow run scope.
archived_atutc_datetimeAn optional tenant identifier that was set in the workflow run scope.
read_atutc_datetimeWhen set, indicates the last time the message was marked as read.
seen_atutc_datetimeWhen set, indicates the last time the message was marked as seen.
link_clicked_atutc_datetimeWhen set, indicates the last time the message was clicked.
inserted_atutc_datetimeThe time the message was generated.
updated_atutc_datetimeThe time the message was last updated.

Message content blocks (ContentBlock)

Each in-app message will contain the contents of the message template that was used to generate the message, which you can use to display your in-app notifications. You'll find this content under the blocks attribute on each FeedItem returned. Each block includes:

Each ContentBlock is one of: MarkdownContentBlock, TextContentBlock, ButtonSetContentBlock defined by the type attribute.

MarkdownContentBlock

Represents a markdown content block that will have rendered HTML content.

keystringA unique key for the block.
renderedstringThe rendered liquid content as HTML.
contentstringThe markdown liquid template string.
typemarkdownThe type of block.

TextContentBlock

Represents a plaintext content block.

keystringA unique key for the block.
renderedstringThe rendered liquid content as plaintext.
contentstringThe plaintext liquid template string.
typetextThe type of block.

ButtonSetContentBlock

Represents a set of one or more buttons that can be rendered in the in-app message.

keystringA unique key for the block.
buttonsActionButton[]A list of buttons to render in the block.
typebutton_setThe type of block.

Each button set block will contain an array of ActionButton objects. Each button includes:

namestringOne of primary or secondary.
labelstringThe label to show on the button.
actionstringThe URI for this action.

Passing through data

When triggering a workflow that generates an in-app message, all of the data in the workflow run scope will be included in the generated in-app message payload. This makes it possible to pass through identifiers from your system to your in-app notifications that you can then use to render custom UI elements.

Here's an example: if you trigger a workflow with { "project_id": "proj_123" } which generates an in-app message, you can expect the data in the FeedItem to include this project_id.

Customizing in-app API responses

It's also possible to override the response of the in-app API to hide sensitive data using an allow/deny list. You can read more on doing so here.

Message statuses

All messages returned from the in-app channel adhere to our message status and engagement APIs. That means it's possible to programmatically mark the messages as seen, read, interacted with, or archived. You can read more in our message status documentation, or read more on how we use these message statuses on the in-app channel.

Working with actionable notifications

In-app notification messages (FeedItem) are "actionable" and can be one of three types:

  • Standard: indicates that the entire cell is potentially actionable (e.g., clicking anywhere on the cell will trigger an action).
  • Single-action: indicates that the notification cell has a single action button that can be clicked.
  • Multi-action: indicates that the notification cell has both a primary and secondary set of actions that can be clicked.

Working with actionable notifications is straightforward. If you're using out-of-the-box Knock UI components, we'll handle the rendering of actionable notifications for you.

If you're building a custom feed implementation, you can check the blocks attribute for the presence of a ButtonSetContentBlock and render the buttons contained within the block accordingly.

←Overview
Security & authentication→