In-app APIs and real-time service
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:
Event | Description |
---|---|
new-message | Emitted 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.
archived
messages are excluded from the feed.Please note, by default all archived
messages are not displayed.
In-app API response
FeedMetadata
FeedItem
Requests to the feed endpoint will return an array of FeedItems
. Each feed item includes:
ContentBlock
)
Message content blocks (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:
Note: when the block type is markdown
, the rendered
content will always be HTML that should be rendered for the in-app message.
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.