Collect multiple events to a single message with the Digest Engine

The digest engine collects multiple trigger events, aggregates them into a single message and delivers it to the subscriber. This becomes useful when a user needs to be notified on a large amount of triggers and you want to avoid sending too many notifications. Novu will automatically batch the incoming trigger events based on the subscriberId and an optional digestKey that can be added to control the digest logic of the events.

Digest Step

After adding a digest step to a workflow, each node that will be below the digest node will be only triggered once in the specified digest interval. You can decide to send messages before adding a digest node and they will be triggered in real-time.

Digest Nodes

In the image above, there are two nodes (Email and SMS) after the digest node and one node (In-App) before the digest node in the workflow.

For this workflow, if we trigger 10 events within the digest interval, the In-App step will be executed 10 times, and Email and SMS will be executed only 1 time with digested events data.

To read more about the full list of parameters, check out the full SDK reference.

Digest Configuration

Digest Key

If specified, the digest engine will group the events based on the digestKey and subscriberId, otherwise the digest engine will group the events based only on the subscriberId.

The digest key might come useful when you want a particular subscriber to get events grouped on a custom field. For example when an actor likes the user’s post, you might want to digest based on the post_id key.

Time Interval

The time interval determines how long the digest engine will wait before sending the message once created. You can specify the amount and the unit that best suits your needs.

Here, in the image below, 5 is the interval amount, and mins is the interval unit. Interval units can be sec(s), min(s), hour(s), or day(s).

Digest Strategy Types

The strategy which Novu should use to handle the digest step. More details on available strategies below.

Novu allows you to define different digest strategies depending on the actual use-case you are trying to achieve. At this point we allow you to select from 2 strategies:

• Regular Strategy
• Look-Back Strategy

Let’s explore them in detail:

Regular Strategy

In regular strategy, a digest will always be created for the specified window time. Which means that from the first event trigger, if no active digest exists for this subscriber, one will be created and the user will receive the message only when the digest window time is reached.

Look-Back Strategy

In the Look-Back strategy, before creating a digest, Novu will check if a message was sent to the user in the Look-back period. If a message was sent, a digest will be created. Otherwise, a message will be sent directly to the user and the digest creation will be skipped.

Lookback digest has two intervals, digest interval and lookback window. First, it checks if any event is triggered within the past lookback window, only then a digest is created for the digest interval. If not, the event is considered non-digest and workflow execution continues to the next step.

Example:

Let’s set the digest interval as 20 minutes and the lookback interval as 15 minutes.

If we trigger the first event. Since it is the first event and there was no event triggered in the past 15 minutes (lookback interval), this event will send a message immediately (without digest). Now, if we trigger a second event within 15 minutes range, then a new digest will be created with this second event. From now on, for the next 20 minutes (digest interval), all triggers will be digested, and after 20 minutes, the workflow will carry forward to the next step with digested events as a payload.

Scheduled Digest

Minutes

It digests events for every specified minutes. For example, as per the image below, events will be digested for 20 minutes and after 20 minutes, workflow will carry forward to the next step. It will be repeated after every 20 minutes.

Hour

It digests events for given hours. After given hours, a new digest is created.

Daily

It digests events for specified days till given time. After those days and time, a new digest is created and events are digested in this new digest.

Weekly

It digests events for specified weekdays. Only at the specified time, the workflow continues to the next step after the digest step. A new digest is created and events are digested in this new digest till these weeks and time.

Defining a digest step

const digestResult = await step.digest("digest", async () => {
  return {
    unit: "days", // 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months'
    amount: 3, // the number of units to digest events for
  };
});

Writing digest content

In many cases, you will need to access all the digested events payload in order to show the user all or parts of the events included in this digest. For example: “John and 5 others liked your photo.”

The digest function returns an array of triggers that have been digested. You can use this array to perform any necessary actions on the digested triggers. Like Sending and email, or updating a database.

const { events } = await step.digest("digest-3-days", async () => {
  return {
    unit: "days", // 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months'
    amount: 3, // the number of units to digest events for
  };
});

await step.email("send-email", async () => {
  const eventCount = events.length;

  return {
    subject: "Digest Email",
    body: `You have ${eventCount} new events`,
  };
});

Step Controls: At the moment, it is not possible to use digest information in step controls. You can only use it from the code, by creating a custom component for handling digested data..

The digest step returns an object with events array. Each event in the array has the following properties:

• id - The job id of the digested event
• time - The time when the event was triggered
• payload - The original payload passed to the event

Changing the step content after triggering the workflow with digest step will not affect the existing digested events.

Frequently Asked Questions

All digest times are in UTC time

If scheduled digest is set for 9:00 AM daily then will the digest be sent at 9:00 AM every day without any event triggered?

If scheduled digest is sent for 9:00 daily, then novu will collect all events triggered between 9:00 AM today till 9:00 AM tomorrow and send the digest at 9:00 AM tomorrow. This process is repeated daily. If there is no any event triggered between 9:00 AM today and 9:00 AM tomorrow, then no digest will be sent.

What is the difference between Regular and Schedules Digest set to 1 Hour?

Both digests are same in this case.