From 85d775e5150559da6b827d55a9a7909d9b949a41 Mon Sep 17 00:00:00 2001 From: zak Date: Wed, 21 Jan 2026 15:07:20 +0000 Subject: [PATCH] Add message conflation section to updates-deletes docs Explain how batching and conflation rules combine multiple update, delete, and append operations that target the same message serial. Covers append concatenation behavior and precedence rules when different operation types interact within a conflation window. --- src/pages/docs/messages/updates-deletes.mdx | 23 +++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx index 1da0630dce..961653df1e 100644 --- a/src/pages/docs/messages/updates-deletes.mdx +++ b/src/pages/docs/messages/updates-deletes.mdx @@ -604,6 +604,29 @@ When appending to a message, you can optionally provide metadata: This metadata will end up in the message's `version` property. See [Message version structure](/docs/messages/updates-deletes#version-structure) for what this looks like. +## Message conflation + +When [server-side batching](/docs/messages/batch#server-side) or [message conflation](/docs/messages#conflation) is enabled, Ably groups update, delete, and append messages received in the configured time window before delivering them to subscribers. +During this window, if multiple operations target the same message (identified by its `serial`), Ably combines them into a single operation. +Instead of receiving every intermediate update, append, or delete, subscribers receive a single message representing the combined result. +For update, delete, and append messages the same behavior applies whether you use batching rules or conflation rules. + +### Append conflation + +Ably concatenates a series of appends to the same message into a single larger append. Subscribers receive one append containing the combined data from all appends in the conflation window, with the operation metadata from the most recent append. +The append messages must all have the same data type (e.g. all strings or all binary) in order to be concatenated correctly. + +### Update and delete conflation + +When an update or delete occurs, it supersedes all previous operations for that message in the time window. +If additional appends follow the update or delete within the same window, Ably combines them: subscribers receive the full message content including those appends, rather than receiving the update followed by separate append operations. + +Conversely, if an update or delete arrives after appends in the conflation window, the update or delete wins and discards the pending appends. + + + ## Get the latest version of a message To retrieve the most recent version of a specific message, use the `getMessage()` method on a REST channel. You can pass either the message's serial identifier as a string, or a message object with a `serial` property.