Batching

note

Batching is currently in Public Beta and under active development. The API may change, and this feature is not covered under the Enterprise SLA.

Batching is an Automations feature that aggregates events and consolidates multiple notifications into a single update. This reduces notification frequency and improves the likelihood of recipients engaging with the content. Batching operates based on the following criteria:

1. Period of inactivity: If no events occur within a defined time span (e.g., one hour), all events since the last notification are bundled into a single notification.
2. Maximum event count: Notifications are held until a specified number of events (e.g., 100) have accumulated. These events are then summarized in a single notification.
3. Maximum wait time: All events that would have triggered notifications within a predefined duration (e.g., 24 hours) are summarized into a single notification.

Batching is supported across various channels (email, SMS, chat, in-app inbox, push) and providers (Twilio, Sendgrid, email SMTP, Slack, MS Teams, WeChat).

Use Cases

Article Performance Summary

When an article is published on a news website, events are generated for each view, comment, and share. Instead of sending a notification for each event, these events can be batched within an automation. Once the initial surge of activity subsides or the maximum wait time is reached, the batch compiles view count, top comments, and share count data. This summary is then sent to the author via email.

Data Warehouse Analytics

A company processing large amounts of data may generate reports at different times. An event is triggered upon each report's completion. With batching, these reports can be grouped and sent in a single email once all the reports for the day are generated.

Social Media Engagement

When a user creates a popular post that receives numerous likes within minutes, batching can be used to notify the user once the post hasn't received new likes for a specified period. For example, "Your post received 17 likes."

Creating A Batch

To create a batch, use the "Add to Batch" action, then click within the batch node to open the editor in the sidebar.

Configuring A Batch

To configure a batch, click on the batch node to open the editor in the sidebar.

Parameter	Description
Wait Period	Defines the period of inactivity before a batch is considered complete. If no events are received within this time frame, the batch will be finalized and sent to the next step.
Max Wait	Defines the maximum amount of time to wait before finalizing the batch. If this time frame is reached, the batch will immediately complete, even if an event had been received within the "wait period."
Retain Items	Defines the number of items to retain and send with the batch. Users can specify any positive integer value. Retention does not affect the tracked count. For example, if Retain Items is set to 10 and 15 items are received, the passed count will be 15, but only 10 items will be included in the batch. Options: First N, Last N, Highest N (requires Sort Key), Lowest N (requires Sort Key), where N is the user-specified number of items to retain.
Sort Key	Required when Highest or Lowest is selected for Retain Items. Defines the key of the data object to be used to determine item ordering. For example, if Sort Key is set to refs.data.upvotes, and the automation is invoked with { "data": { "upvotes": 5 }}, 5 will be the value used to determine the order and position of the event in the items array.
Max Items	(Optional) Defines the maximum number of events to include in a batch before completion. When a batch has received this number of events, it will immediately finalize and send the batch to the next step.
Scope	Defines the scope of the batch, determining how events are grouped together. Options: Global (default), User, Dynamic. See Batch Scope for more details.
Category Key	(Optional) Allows events to be grouped by categories. See Working with Categories for more details.

Batch Scope

The Scope parameter in the batch node configuration allows you to define the scope of the batch. It determines how events are grouped together within the batch. There are three options for the batch scope:

Scope	Description
Global (default)	• Events are grouped together based on the batch step ID. • The batch will trigger and send the grouped events to the next step when either the maximum number of events is reached or the specified time period elapses.
User	• Events are grouped together based on the unique combination of user_id and batch step ID. • The batch will trigger when enough events associated with a specific user are added to the batch or when the specified time period elapses, allowing for user-specific batching of events.
Dynamic	• Events are grouped together based on the Batch Key specified in the batch configuration, regardless of the batch step ID or automation they belong to. • This allows for flexible event grouping based on specific criteria, but may lead to unexpected results as events from different batch steps or automations may be merged.

caution

Please note that the dynamic scope behavior is subject to change in future revisions of the automation system.

Invoking a Batch

• When a batch node is invoked, Courier checks for an ongoing batch run for the configured scope.
  • If none exists:
    1. A new batch run is created.
    2. The current automation run is marked as pending.
    3. The system waits until the batch is complete before proceeding to the next step.
  • If an existing batch run is found:
    1. The data object is added to the existing batch.
    2. The current automation run is terminated.
    3. Steps connected to the batch are not executed, ensuring that nodes following a batch node are only executed once per batch run.

{
  batch: {
    // The number of events received for this category, may be different than items.length
    // depending on item retention configuration.
    count: number;
    // An array of the data objects of each automation added to this batch.
    items: any[];
  }
}

Example: If a batch automation is invoked 3 times with the following values:

Invoke 1

{
  data: {
    like_from: "Drew";
  }
}

Invoke 2

{
  data: {
    like_from: "Alex";
  }
}

Invoke 3

{
  data: {
    like_from: "Abby";
  }
}

The steps following the batch node would be provided this data object:

Completed Batch Data

{
  batch: {
    count: 3,
    items: [
      { like_from: "Drew" },
      { like_from: "Alex" },
      { like_from: "Abby" },
    ]
  }
}

This data can be accessed from a notification template using variable syntax.

Accessing batch data from a notification template

Working With Categories

When the Category Key is set to a dynamic value such as refs.data.category_key, events can be grouped by category in a batch run. In this case, the batch is aggregated by category:

Accessing batch data from a notification template

Example: In the batch node, Category Key is set to refs.data.category_key. Each time the automation is invoked, a category_key is supplied.

Given the following invocations:

Invoke 1

{
  data: {
    category_key: "likes",
    like_from: "Drew"
  }
}

Invoke 2

{
  data: {
    category_key: "likes",
    like_from: "Alex"
  }
}

Invoke 3

{
data: {
  category_key: "comments",
  comment: "Excellent post!"
  }
}

The automation steps following the batch node would receive this data object:

Completed Batch Data

{
  "batch": {
    "likes": {
      "count": 2,
      "items": [
        { "like_from": "Drew" },
        { "like_from": "Alex" }
      ],
    },
    "comments": {
      "count": 1,
      "items": [
        { "comment": "Excellent post!" }
      ],
    },
  }
}