[ECO-5135] Updates the Chat docs to include code examples for chat-swift #2315
There are no files selected for viewing
This file contains 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
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,14 +5,15 @@ product: chat | |
| languages: | ||
| - javascript | ||
| - react | ||
| - swift | ||
| --- | ||
|
|
||
| The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 24 hours by default. You can extend this up to 30 days by "contacting us":https://forms.gle/SmCLNFoRrYmkbZSf8. | ||
|
|
||
| h2(#get). Retrieve previously sent messages | ||
|
|
||
| blang[javascript,swift]. | ||
| Use the <span lang="javascript">"@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get</span><span lang="swift">"@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Messages.html#get</span> method to retrieve messages that have been previously sent to a room: | ||
|
|
||
| blang[react]. | ||
| Use the "@get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#get method available from the response of the @useMessages@ hook to retrieve messages that have been previously sent to a room. | ||
|
|
@@ -50,20 +51,38 @@ const MyComponent = () => { | |
| }; | ||
| ``` | ||
|
|
||
| ```[swift] | ||
| let paginatedResult = try await room.messages.get(options: .init(orderBy: .newestFirst)) | ||
| print(paginatedResult.items) | ||
| if let next = try await paginatedResult.next { | ||
| print(next.items) | ||
| } else { | ||
| print("End of messages") | ||
| } | ||
| ``` | ||
|
|
||
| The following optional parameters can be passed when retrieving previously sent messages: | ||
|
|
||
| blang[javascript]. | ||
| |_. 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. | | ||
| | direction | The direction in which to retrieve messages from; either @forwards@ or @backwards@. | | ||
| | limit | Maximum number of messages to be retrieved, up to 1,000. | | ||
|
|
||
| blang[swift]. | ||
| |_. 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 direction in which to retrieve messages from; either @oldestFirst@ or @newestFirst@. | | ||
| | limit | Maximum number of messages to be retrieved, up to 1,000. | | ||
|
Comment on lines
+73
to
+78
There was a problem hiding this comment. Should this not have parity between JS and Swift? @AndyTWF There was a problem hiding this comment. This divergence hasn't yet had a DR and thus hasn't been incorporated into JS - it was sorta an informal Slack conversation. I suggest we allow the lack of parity for now until we get a chance to update JS - shouldn't take long but I don't want to block this PR getting merged. There was a problem hiding this comment. So this is now agreed on |
||
|
|
||
| h2(#subscribe). 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":/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. | ||
|
|
||
| blang[javascript,swift]. | ||
| Use the <span lang="javascript">"@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#getPreviousMessages</span><span lang="swift">"@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.MessageSubscription.html#getPreviousMessages</span> function returned as part of a "message subscription":/chat/rooms/messages#subscribe response to only retrieve messages that were received before the listener was subscribed to the room: | ||
|
|
||
| blang[react]. | ||
| Use the "@getPrevious()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#getPreviousMessages method available from the response of the @useMessages@ hook to only retrieve messages that were received before the listener subscribed to the room. As long as a defined value is provided for the listener, and there are no message discontinuities, @getPreviousMessages()@ will return messages from the same point across component renders. If the listener becomes undefined, the subscription to messages will be removed. If you subsequently redefine the listener then @getPreviousMessages()@ will return messages from the new point of subscription. | ||
|
|
@@ -114,6 +133,17 @@ const MyComponent = () => { | |
| }; | ||
| ``` | ||
|
|
||
| ```[swift] | ||
| let messagesSubscription = try await room.messages.subscribe() | ||
| let paginatedResult = try await messagesSubscription.getPreviousMessages(params: .init(limit: 50)) // `orderBy` here is ignored and always `newestFirst` | ||
| print(paginatedResult.items) | ||
| if let next = try await paginatedResult.next { | ||
| print(next.items) | ||
| } else { | ||
| print("End of messages") | ||
| } | ||
| ``` | ||
|
|
||
| The following parameters can be passed when retrieving previously sent messages: | ||
|
|
||
| |_. Parameter |_. Description | | ||
|
|
||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If it's only the link that will be different then I think it may be clearer to combine it into a single block, e.g.:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, here the property name is also different (which is probably something that should be fixed fyi @AndyTWF @lawrence-forooghian @ttypic)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I spoke to Andy about this separately and it has been updated for JS in a separate PR (#2300).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That PR modifies the same lines, I guess it should be merged first before me to proceed with this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
updated