Skip to content

chat docs: update history.mdx for specific use-cases #3124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sacOO7 wants to merge 3 commits into
base: main
Choose a base branch
from
+29 −14
Open

chat docs: update history.mdx for specific use-cases #3124

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ef8437c
Updated doc for chat history, added section ordering use-case and def…
sacOO7 Jan 20, 2026
0313f52
Addressed all review comments on the PR
sacOO7 Jan 29, 2026
5cc9dba
Merge remote-tracking branch 'origin/main' into update/chat-history-doc
sacOO7 Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 29 additions & 14 deletions src/pages/docs/chat/rooms/history.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,19 +88,30 @@ 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. |
| `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. |
| 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 <a id="understanding-message-ordering"/>
Copy link
Contributor

@AndyTWF AndyTWF Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this need to be an entire section? At most I would have this as a single sentence, e.g. "Most chat applications will use newestFirst to display messages from newest to oldest"

Copy link
Contributor Author

@sacOO7 sacOO7 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is required to describe message ordering semantics and subscriber message delivery. Without this documentation, the LLM has repeatedly hallucinated, as referenced in https://ably.atlassian.net/browse/FTF-489

Copy link
Contributor

@AndyTWF AndyTWF Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, we need the information - my question is does it have to be an entire section, or could it literally be a sentence at the end of the previous section?

So the previous section has a table and then a sentence describing things?

Copy link
Contributor

@m-hulbert m-hulbert Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with Andy here - also:

The orderBy parameter determines both which messages are retrieved and their return order:

I think this is a little confusing and the emphasis shouldn't be on which


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 showing newest message at the bottom of the UI.

## Retrieve messages sent prior to subscribing <a id="subscribe"/>

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()`. 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.
Copy link
Contributor

@m-hulbert m-hulbert Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than newestFirst order I think this would read better as:

"Messages are returned in order, from the most recent to the oldest."

We avoid people needing to know what the property does then (even if the name is somewhat obvious, admittedly).


<If lang="javascript,swift,kotlin">
Use the <If lang="javascript">[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)</If><If lang="swift">[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29))</If><If lang="kotlin">[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html)</If> 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 <If lang="javascript">[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#historyBeforeSubscribe)</If><If lang="swift">[`historyBeforeSubscribe(withParams:)`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscriptionresponse/historybeforesubscribe%28withparams%3A%29)</If><If lang="kotlin">[`historyBeforeSubscribe()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages-subscription/history-before-subscribe.html)</If> 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.
</If>

<If lang="jetpack">
Expand Down Expand Up @@ -233,13 +244,17 @@ fun HistoryBeforeSubscribeComponent(room: Room) {
```
</Code>

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 | 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 |

| 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. |
<Aside>
The `orderBy` parameter is not available for `historyBeforeSubscribe()`. Messages are always returned in `newestFirst` order.
Copy link
Contributor

@m-hulbert m-hulbert Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per above: I don't think we need to mention or associate orderBy here as it implies someone would have had to read the whole page to understand this section. We can just say that they're always returned from most recent to oldest.

</Aside>

<If lang="jetpack">

Expand Down