12 new comments, not 12 emails.
Batch a notification type over a window, or into a daily or weekly digest in each recipient's time zone. You keep sending one notification per event.
Batching is a setting on the notification type. Sends don't change: each comment, like or mention is still one notifications.send, and Notify collects them per recipient (and per key, such as the post) until the batch closes.
1
A window
The batch closes window_seconds after its first notification. With sliding, every new one restarts the window, so a burst goes out once it is quiet, but never later than max_window_seconds after the first.
await notify.notificationTypes.update("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f10", {
batch: {
mode: "window",
key: "post_id", // one batch per post
window_seconds: 600, // send 10 minutes after the first comment…
sliding: true, // …or after the latest, while they keep coming
max_window_seconds: 3600,
max_items: 5, // batch.items holds the 5 newest
inbox: "collapse", // one inbox item per batch, updated live
},
});2
A digest
daily, or weekly on a weekday, at a local time: the recipient's time zone, else your workspace default, else UTC.
await notify.notificationTypes.update("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f11", {
batch: { mode: "digest", schedule: { frequency: "daily", time: "09:00" }, inbox: "each" },
});
// Sends don't change: each comment is one call, and the digest collects them.
await notify.notifications.send(
{ type: "comment.digest", recipients: ["user_123"], data: { text: "Lovely post!" }, actor: { name: "Ada" } },
{ idempotencyKey: "comment.digest:c_77" },
);3
Templates
When the batch closes, every batched channel (email, mobile push, browser push, webhook) sends one message rendered with batch. In a push title: {{batch.latest.actor.name}}{{#batch.has_others}} and {{batch.others_count}} others{{/batch.has_others}} commented. Email templates in Mail get the same object for {{#each batch.items}}.
| Variable | What it is |
|---|---|
batch.count | Notifications in the batch (all of them). |
batch.items | The newest max_items, each with its data, actor and created_at. |
batch.latest / batch.earliest | The newest and the oldest item. |
batch.has_others / batch.others_count | For "Ada and 3 others": more than one item, and how many besides the latest. |
batch.actors / batch.actor_count | The distinct actors, newest first, and how many. |
batch.more_count | Items not listed in batch.items. |
batch.key | The batch key value (the post id). |
4
The inbox
The inbox never waits. With inbox: "collapse" (the default) each open batch is one item, replaced, and unread again, as notifications join it, so the bell counts one. With "each" every notification gets its own item.
5
What still applies
- Preferences, quiet hours, the per-recipient limits and the type's throttle apply when the batch is sent, and count it once.
- Cancelling a notification takes it out of its batch; a batch whose sends were all cancelled closes as cancelled.
- Critical types are never batched, and batching works with
alwaysrouting (no fallback steps). Scheduled sends of a batched type are refused: the batch decides when. - The message log shows each delivery as
scheduled: batcheduntil its batch closes; then one carries the message and the others areskipped: batched_into, with thebatch_id.dry_runand the explain tool say which batch a send would join and when it closes.
for await (const b of notify.batches.list({ recipient: "user_123", state: "open" })) {
console.log(b.type, b.key, b.item_count, b.flush_at);
}
const closed = await notify.batches.flush("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f20");
console.log(closed.batch.payload); // what the templates got as batch.*