Message statuses

How to work with the Knock message statuses to understand notification delivery and engagement rates.

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, a sent 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 and marked 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.

1A) Unseen (seen_at: null)

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.

1B) Seen (seen_at: <ISO8601-timestamp>)

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.

2A) Unread (read_at: null)

The message has not been opened or read by the recipient.

2B) Marked as read / opened (read_at: <ISO8601-timestamp>)

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:

3A) Unclicked (clicked_at: null)

No part of the message or links within have been clicked.

3B) Clicked (clicked_at: <ISO8601-timestamp>)

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.

4A) Unarchived (archived_at: null)

The message has not been marked as archived.

4B) Archived (archived_at: <ISO8601-timestamp>)

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.

← Delivering notifications
Link & open tracking →