Message statuses
Knock uses the Message model to represent a notification delivered to a recipient on a particular channel. Knock Messages can have one or more statuses, which indicate the delivery state of your notification or how your recipient is engaging with the message. Knock captures changes in message status as Message Events, which you can hook into with outbound webhooks.
This guide covers message statuses and events in detail.
Statuses
Knock manages two types of notification statuses:
- Delivery status — Was the message successfully delivered to your messaging providers and to your recipient? Delivery statuses are mutually exclusive, hierarchical, and implicitly managed by Knock as part of notification delivery.
- Engagement status — How has your recipient engaged with the notification once received? A message can have multiple engagment statuses, or none. Knock will implicitly manage some engagement statuses for you, but you can also manage them yourself via the Knock API.
Delivery status
When you trigger a Knock workflow, any channel step within that workflow generates a Message for each recipient. Once the message is generated, Knock manages delivery to the recipient via the downstream provider for your channel (e.g. SendGrid for email delivery) on your behalf. Knock uses delivery status to track this delivery process and show you where a given message resides within it.
You can use the "Logs" tab in the message detail view in the Knock dashboard to examine the history of requests Knock makes to the downstream provider to determine delivery status. These delivery logs can be especially helpful to understand an unexpcted delivery status.
Here is an overview of the possible delivery statuses. Delivery statuses are not uniform across channels, and we highlight these differences they exist. Note that delivery status is mutually exclusive and hierarchical—a message can only have one delivery status at a time and will always progress through its delivery statuses in the order presented below.
Delivery status is displayed as the "Status" field in the message detail view in the Knock dashboard.
1) Queued
Your message has been created but it is still queued and waiting to be sent to the provider.
2A) Sent
Your message has successfully made it from Knock to the delivery provider. It is their responsibility to ensure the message is properly delivered to the recipient. Knock may be awaiting further information to determine if the message was successfully delivered.
On a per-channel level, sent
means that:
- Chat — Your message has successfully been sent by Knock to the destination chat platform.
- Email — Your message made it to the delivery provider. We're waiting to learn if it made it to recipient.
- In-app — In-app messages automatically skip to the
delivered
status. We always successfully deliver the message to the Knock Feed API. - Push — Your message has successfully been sent by Knock to the destination push platform.
- SMS — Your message made it to the delivery provider. We're waiting to learn if it made it to recipient.
2B) Not sent
Your message was processed successfully but was not sent to the downstream provider because your channel is in sandbox mode.
3) Delivered
We've received confirmation from the delivery provider that your message was successuly sent to the recipient.
On a per-channel level, delivered
means that:
- Email — Your message was successfully delivered to the recipient's email service provider.
- In-app — Your message was successfully delivered to the recipient's feed.
- Push — We do not support delivery tracking for push channels, so push channel messages will never have a delivery status greater than
sent
. You can set up delivery tracking by introducing a handler into your mobile app to tell Knock when the message has successfully made it to your recipient's device. - SMS — Your message was successfully sent to the recipient's SMS provider. Note that not all SMS delivery providers support delivery tracking. See the Knock integration guides for SMS providers for more information.
- Chat — Delivery tracking is not available for chat platforms, so chat channel messages will never have a delivery status greater than
sent
. In most cases, asent
status will also mean that the message has been delivered to the recipient.
4) Undelivered
Your message was not processed successfully and never made it from Knock to the delivery provider. You can use the message delivery logs to help debug what may have gone wrong between Knock and the downstream provider.
Engagement status
Once delivered, Knock uses a set of engagement statuses to track how the recipient interacts with the notification. There are a few important things to note about how this works:
- Engagement statuses are mutually inclusive. Unlike delivery status, a message can have zero, one, or multiple engagement statuses. As an example, an in-app message can have an engagement status of both
seen
andmarked as read
. - Engagement statuses are hierarchical. Like delivery status, engagement statuses do have a concept or hierarchy. Knock uses this hierarchy when evaluating message status step conditions. If a message has multiple engagement statuses, the one with the highest precedence is used for such comparisons.
- Implicitly managed only sometimes. In a couple cases, Knock will manage engagement status on your behalf. The Knock React SDK will set engagement statuses for your in-app feed channels. Knock will also manage engagement statuses for any channel configured to use Knock link and open tracking. In all cases, you can use the Knock Message status API to explicitly manage engagement statuses yourself.
Knock uses message timestamp fields to model engagement statuses. Below we review the possible engagement statuses and various per-channel caveats for how they work.
Once a message has been sent or delivered to a recipient, Knock starts tracking the engagement status for that message to understand recipient interaction with it.
seen_at: null
)
1A) Unseen (Your message has successfully reached the recipient, but Knock doesn't yet have confirmation that they've engaged in any way. This is the base engagement status for all channels.
For certain channels if you do not have Knock link and open tracking enabled, your message will never have more than the unseen engagement status without explicit management via the Knock API.
seen_at: <ISO8601-timestamp>
)
1B) Seen (Knock only implicitly manages this status for the in-app feed channel.
The seen
status indicates that the message has been retrieved for display in the recipient's in-app feed at least once. The timestamp represents the time of the most recent action. The seen
status is separate from an opened/read status, in that it doesn't indicate the recipient has explicitly interacted with the message itself.
read_at: null
)
2A) Unread (The message has not been opened or read by the recipient.
read_at: <ISO8601-timestamp>
)
2B) Marked as read / opened (The message has been opened and read by the recipient at least once. The timestamp represents the time of the most recent action.
Knock will implicitly manage this status only for the following channel configurations:
- Email — Knock open tracking needs to be enabled.
- In-app — When you're using the Knock ReactFeedProvider SDK.
- Push — Not currently supported.
- SMS — Not directly supported. But, if Knock link tracking is enabled, we will count a link-click action as also an open event.
- Chat — Not directly supported. But, if Knock link tracking is enabled, we will count a link-click action as also an open event.
clicked_at: null
)
3A) Unclicked (No part of the message or links within have been clicked.
clicked_at: <ISO8601-timestamp>
)
3B) Clicked (A link or action within your message was clicked by the recipient. The timestamp represents the time of the most recent action.
Knock will implicitly manage this status only for the following channel configurations:
- Email — Knock link tracking needs to be enabled.
- In-app — Knock link tracking needs to be enabled for link-clicks to count towards this status. In addition, for in-app messages where the message is itself a link, message clicks will also count. (Note: that clicking “mark all as read” does not result in a message being marked as clicked; rather, as the phrasing implies, we bulk update the message engagement statuses to opened/read.)
- Push — Not currently supported.
- SMS — Knock link tracking needs to be enabled.
- Chat — Knock link tracking needs to be enabled.
archived_at: null
)
4A) Unarchived (The message has not been marked as archived.
archived_at: <ISO8601-timestamp>
)
4B) Archived (Knock only implicitly manages this status for the in-app feed channel.
The message has been archived by the recipient. The timestamp represents the time of the most recent action.
Message events
Knock records each change in message status, whether delivery or engagement, as a message event. You can view these events in chronological order of occurrence in the message timeline view in the Knock dashboard. Knock also uses these message events to power webhooks. See our guide on outbound webhooks to learn more about how you can hook into the Knock message status lifecycle.