chat docs: update history.mdx for specific use-cases #3124
+24
−9
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughThis pull request updates documentation for message history retrieval functionality, adding explicit parameter defaults (start, end, orderBy, limit) and a new section explaining message ordering behavior (newestFirst vs oldestFirst) to clarify API semantics and reduce implementation confusion. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
sacOO7
changed the title
sacOO7
force-pushed
the
update/chat-history-doc
branch
from
6f882b7 to
fea3179
Compare
…ault param values
sacOO7
force-pushed
the
update/chat-history-doc
branch
from
fea3179 to
ef8437c
Compare
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/pages/docs/chat/rooms/history.mdx`:
- Line 114: The Swift typedoc link contains an extra closing parenthesis; edit
the line referencing historyBeforeSubscribe(withParams:) and remove the trailing
")" from the URL in the If lang="swift" link so the URL matches the intended
typedoc link exactly (keep the displayed label
[`historyBeforeSubscribe(withParams:)`] and only correct the href).
- Line 111: Remove the incorrect inline link on the function name so
`historyBeforeSubscribe()` is plain text and add a separate, clearly worded link
to the ordering guidance (the "understanding-message-ordering" anchor) in the
surrounding sentence; specifically, edit the paragraph that currently contains
[`historyBeforeSubscribe()`](`#understanding-message-ordering`) to render
historyBeforeSubscribe() without a link and include a second sentence or clause
linking to the ordering guidance (e.g., "See the ordering guidance in the
understanding-message-ordering section") so the function name and the ordering
documentation are distinct.
| ## 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()`](#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. |
There was a problem hiding this comment.
Fix the historyBeforeSubscribe() link target.
The function name currently links to the ordering section, which is confusing. Consider removing the link on the function name and linking the ordering guidance separately.
🔧 Proposed fix
-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. For ordering details, see [Understanding message ordering](`#understanding-message-ordering`). This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 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. For ordering details, see [Understanding message ordering](`#understanding-message-ordering`). This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap. |
🤖 Prompt for AI Agents
In `@src/pages/docs/chat/rooms/history.mdx` at line 111, Remove the incorrect
inline link on the function name so `historyBeforeSubscribe()` is plain text and
add a separate, clearly worded link to the ordering guidance (the
"understanding-message-ordering" anchor) in the surrounding sentence;
specifically, edit the paragraph that currently contains
[`historyBeforeSubscribe()`](`#understanding-message-ordering`) to render
historyBeforeSubscribe() without a link and include a second sentence or clause
linking to the ordering guidance (e.g., "See the ordering guidance in the
understanding-message-ordering section") so the function name and the ordering
documentation are distinct.
| 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. | ||
|
|
||
| <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. |
There was a problem hiding this comment.
Fix the Swift typedoc link URL.
There’s an extra closing parenthesis at the end of the Swift link, which likely breaks the URL.
🔧 Proposed fix
-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.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 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. |
🤖 Prompt for AI Agents
In `@src/pages/docs/chat/rooms/history.mdx` at line 114, The Swift typedoc link
contains an extra closing parenthesis; edit the line referencing
historyBeforeSubscribe(withParams:) and remove the trailing ")" from the URL in
the If lang="swift" link so the URL matches the intended typedoc link exactly
(keep the displayed label [`historyBeforeSubscribe(withParams:)`] and only
correct the href).
maratal
approved these changes
Jan 23, 2026
| | 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).** | |
Collaborator
There was a problem hiding this comment.
Why not just "Defaults to earliest available message".
| | `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. |
Collaborator
There was a problem hiding this comment.
I would add "... for chronological display (newest at the bottom of the UI)." or something. Or remove this remark at all.
| | 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).** | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.