From ef8437cd1742795bf12f4090748932c92b77635c Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Tue, 20 Jan 2026 18:12:16 +0530 Subject: [PATCH 1/2] Updated doc for chat history, added section ordering use-case and default param values --- src/pages/docs/chat/rooms/history.mdx | 33 +++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index 378c907732..047e3a26bf 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -90,14 +90,25 @@ The following optional parameters can be passed when retrieving previously sent | Parameter | Description | | --------- | ----------- | -| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | -| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | -| orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. | -| limit | Maximum number of messages to be retrieved per page, up to 1,000. | +| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. **Defaults to no lower bound (earliest available message).** | +| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. **Defaults to current time.** | +| orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. **Defaults to `newestFirst`.** | +| limit | Maximum number of messages to be retrieved per page, up to 1,000. **Defaults to 100.** | + +### Understanding message ordering + +The `orderBy` parameter determines both *which* messages are retrieved and their return order: + +| Order | Retrieves | Returns | Use case | +| ----- | --------- | ------- | -------- | +| `newestFirst` (default) | Most recent messages | `[newest, ..., oldest]` | Standard chat UIs | +| `oldestFirst` | Oldest messages from room start | `[oldest, ..., newest]` | Archives, exports, admin tools | + +**For typical chat applications:** Use `newestFirst` (default) to get recent messages, then reverse the result for chronological display. ## Retrieve messages sent prior to subscribing -Users can also retrieve historical messages that were sent to a room before the point that they registered a listener by [subscribing](/docs/chat/rooms/messages#subscribe). The order of messages returned is from most recent, to oldest. This is useful for providing conversational context when a user first joins a room, or when they subsequently rejoin it later on. It also ensures that the message history they see is continuous, without any overlap of messages being returned between their subscription and their history call. +Retrieve historical messages sent before subscribing using [`historyBeforeSubscribe()`](#understanding-message-ordering). Messages are returned in `newestFirst` order. This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap. Use the [`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29))[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html) function returned as part of a [message subscription](/docs/chat/rooms/messages#subscribe) response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -233,13 +244,17 @@ fun HistoryBeforeSubscribeComponent(room: Room) { ``` -The following parameters can be passed when retrieving previously sent messages: +The following optional parameters can be passed when retrieving messages before subscribing: | Parameter | Description | | --------- | ----------- | -| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | -| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | -| limit | Maximum number of messages to be retrieved per page, up to 1,000. | +| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. **Defaults to no lower bound (earliest available message).** | +| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. **Defaults to current time.** | +| limit | Maximum number of messages to be retrieved per page, up to 1,000. **Defaults to 100.** | + + From 0313f5232192e4c8752b1c4543668e95992ffda7 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Thu, 29 Jan 2026 11:21:54 +0530 Subject: [PATCH 2/2] Addressed all review comments on the PR --- src/pages/docs/chat/rooms/history.mdx | 28 +++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index 047e3a26bf..cdcaf048ef 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -88,12 +88,12 @@ println("End of messages") The following optional parameters can be passed when retrieving previously sent messages: -| Parameter | Description | -| --------- | ----------- | -| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. **Defaults to no lower bound (earliest available message).** | -| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. **Defaults to current time.** | -| orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. **Defaults to `newestFirst`.** | -| limit | Maximum number of messages to be retrieved per page, up to 1,000. **Defaults to 100.** | +| Parameter | Description | Default | +| --------- | ----------- | ------- | +| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | Earliest available message | +| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | Current time | +| orderBy | The order in which to retrieve messages from; either `oldestFirst` or `newestFirst`. | `newestFirst` | +| limit | Maximum number of messages to be retrieved per page, up to 1,000. | 100 | ### Understanding message ordering @@ -104,14 +104,14 @@ The `orderBy` parameter determines both *which* messages are retrieved and their | `newestFirst` (default) | Most recent messages | `[newest, ..., oldest]` | Standard chat UIs | | `oldestFirst` | Oldest messages from room start | `[oldest, ..., newest]` | Archives, exports, admin tools | -**For typical chat applications:** Use `newestFirst` (default) to get recent messages, then reverse the result for chronological display. +**For typical chat applications:** Use `newestFirst` (default) to get recent messages, then reverse the result for showing newest message at the bottom of the UI. ## Retrieve messages sent prior to subscribing -Retrieve historical messages sent before subscribing using [`historyBeforeSubscribe()`](#understanding-message-ordering). Messages are returned in `newestFirst` order. This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap. +Retrieve historical messages sent before subscribing using `historyBeforeSubscribe()`. Messages are returned in `newestFirst` order. This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap. -Use the [`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29))[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html) function returned as part of a [message subscription](/docs/chat/rooms/messages#subscribe) response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages. +Use the [`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29)[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html) function returned as part of a [message subscription](/docs/chat/rooms/messages#subscribe) response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -246,11 +246,11 @@ fun HistoryBeforeSubscribeComponent(room: Room) { The following optional parameters can be passed when retrieving messages before subscribing: -| Parameter | Description | -| --------- | ----------- | -| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. **Defaults to no lower bound (earliest available message).** | -| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. **Defaults to current time.** | -| limit | Maximum number of messages to be retrieved per page, up to 1,000. **Defaults to 100.** | +| Parameter | Description | Default | +| --------- | ----------- | ------- | +| start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. | Earliest available message | +| end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. | Current time | +| limit | Maximum number of messages to be retrieved per page, up to 1,000. | 100 |