From 2d12da7a5b2f2d45b15e0b9445c3e2d6b7b4b7e5 Mon Sep 17 00:00:00 2001 From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com> Date: Wed, 21 Jan 2026 12:58:07 +0100 Subject: [PATCH 1/2] Addresses feedback from review --- src/pages/docs/chat/rooms/history.mdx | 6 +- src/pages/docs/chat/rooms/index.mdx | 2 +- .../docs/chat/rooms/message-reactions.mdx | 4 ++ src/pages/docs/chat/rooms/messages.mdx | 60 +++++++++---------- src/pages/docs/chat/rooms/presence.mdx | 28 +++++---- src/pages/docs/chat/rooms/reactions.mdx | 4 ++ src/pages/docs/chat/rooms/replies.mdx | 4 ++ src/pages/docs/chat/rooms/typing.mdx | 10 ++-- src/pages/docs/chat/setup.mdx | 4 ++ .../docs/guides/chat/build-livestream.mdx | 4 ++ 10 files changed, 75 insertions(+), 51 deletions(-) diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index d95a33b22e..9ab4d50487 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -3,12 +3,12 @@ title: Message storage and history meta_description: "Retrieve previously sent messages from history." --- -The history feature enables users to retrieve messages that have been previously sent in a room. [Message persistence](/docs/chat/rooms#persistence) is enabled by default for all chat rooms, with messages stored for 30 days. You can extend this retention period up to 365 days by [contacting us](https://ably.com/support). +The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support). ## Retrieve previously sent messages - -Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. + +Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. diff --git a/src/pages/docs/chat/rooms/index.mdx b/src/pages/docs/chat/rooms/index.mdx index 616f5aba81..1cfec49d33 100644 --- a/src/pages/docs/chat/rooms/index.mdx +++ b/src/pages/docs/chat/rooms/index.mdx @@ -190,7 +190,7 @@ By default the `ChatRoomProvider` will automatically call [`release()`](https:// To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions. - + Once an instance of a room has been created using `rooms.get()`, clients attach to it to start receiving messages and events from the room. Use the [`attach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/attach%28%29)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/attach.html) method on a room to attach to it: diff --git a/src/pages/docs/chat/rooms/message-reactions.mdx b/src/pages/docs/chat/rooms/message-reactions.mdx index 57d86dcd11..38206b50e3 100644 --- a/src/pages/docs/chat/rooms/message-reactions.mdx +++ b/src/pages/docs/chat/rooms/message-reactions.mdx @@ -394,6 +394,10 @@ fun RemoveMessageReactionComponent(room: Room, message: Message) { ``` + + ## Messages and reactions The `Message` object contains a `reactions` property which is an object that looks like this: diff --git a/src/pages/docs/chat/rooms/messages.mdx b/src/pages/docs/chat/rooms/messages.mdx index afd3dd37e7..776376a170 100644 --- a/src/pages/docs/chat/rooms/messages.mdx +++ b/src/pages/docs/chat/rooms/messages.mdx @@ -104,19 +104,19 @@ The following are the properties of a message: | Property | Description | Type | | -------- | ----------- | ---- | -| serial | An Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages. | String | -| clientId | The client identifier of the user that created the message. | String | -| text | The message contents. | String | -| headers | Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. | Object | -| metadata | Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. | Object | -| timestamp | The time the message was created. | Date | -| action | The latest action performed on this message, such as `message.create`, `message.update` or `message.delete`. | String | -| version | Contains information about the current version of the message. For `message.create` actions, only `serial` and `timestamp` are set. For `message.update` and `message.delete` actions, additional fields are included. | Object | -| | `serial`: An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version.serial` is identical to `serial` if the action is `message.create`. | String | -| | `timestamp`: The time the action was performed. It will be identical to `timestamp` if the action is a `message.create`. | Date | -| | `clientId`: The client identifier of the user that created this version of the message. Only set for `message.update` and `message.delete` actions. | String or undefined | -| | `description`: Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | String or undefined | -| | `metadata`: Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | Object or undefined | +| `serial` | An Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages. | `string` | +| `clientId` | The client identifier of the user that created the message. | `string` | +| `text` | The message contents. | `string` | +| `headers` | Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. | `object` | +| `metadata` | Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. | `object` | +| `timestamp` | The time the message was created. | `date` | +| `action` | The latest action performed on this message, such as `message.create`, `message.update` or `message.delete`. | `string` | +| `version` | Contains information about the current version of the message. For `message.create` actions, only `serial` and `timestamp` are set. For `message.update` and `message.delete` actions, additional fields are included. | `object` | +| `serial`| An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version.serial` is identical to `serial` if the action is `message.create`. | `string` | +| `timestamp` | The time the action was performed. It will be identical to `timestamp` if the action is a `message.create`. | `date` | +| `clientId` | The client identifier of the user that created this version of the message. Only set for `message.update` and `message.delete` actions. | `string` or `undefined` | +| `description` | Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `string` or `undefined` | +| `metadata` | Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `object` or `undefined` | See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application. @@ -524,13 +524,13 @@ The updated message response is identical to the structure of a message, with th | Property | Description | Type | | -------- | ----------- | ---- | -| action | Set to `message.update`. | string | -| version | Contains additional fields compared to `message.create` action: | object | -| | `serial`: Set to the serial of the update action. | string | -| | `timestamp`: Set to the time the message was updated. | Date | -| | `clientId`: The client identifier of the user who performed the update. | String or undefined | -| | `description`: Optional description provided in the update request. | String or undefined | -| | `metadata`: Optional metadata provided in the update request. | Object or undefined | +| `action` | Set to `message.update`. | `string` | +| `version` | Contains additional fields compared to `message.create` action: | `object` | +| `serial`| Set to the serial of the update action. | `string` | +| `timestamp` | Set to the time the message was updated. | `date` | +| `clientId` | The client identifier of the user who performed the update. | `string` or `undefined` | +| `description` | Optional description provided in the update request. | `string` or `undefined` | +| `metadata` | Optional metadata provided in the update request. | `object` or `undefined` | ## Delete a message @@ -774,16 +774,16 @@ The deleted message response is identical to the structure of a message, with th | Property | Description | Type | | -------- | ----------- | ---- | -| action | Set to `message.delete`. | string | -| version | Contains additional fields compared to `message.create` action: | object | -| | `serial`: Set to the serial of the deletion action. | string | -| | `timestamp`: Set to the time the message was deleted. | Date | -| | `clientId`: The client identifier of the user who performed the deletion. | String or undefined | -| | `description`: Optional description provided in the delete request. | String or undefined | -| | `metadata`: Optional metadata provided in the delete request. | Object or undefined | -| text | Set to the empty string. | string | -| metadata | Set to the empty object. | Object | -| headers | Set to the empty object. | Object | +| `action` | Set to `message.delete`. | `string` | +| `version` | Contains additional fields compared to `message.create` action: | `object` | +| `serial` | Set to the serial of the deletion action. | `string` | +| `timestamp` | Set to the time the message was deleted. | `date` | +| `clientId` | The client identifier of the user who performed the deletion. | `string` or `undefined` | +| `description` | Optional description provided in the delete request. | `string` or `undefined` | +| `metadata` | Optional metadata provided in the delete request. | `object` or `undefined` | +| `text` | Set to the empty string. | `string` | +| `metadata` | Set to the empty object. | `object` | +| `headers` | Set to the empty object. | `object` | ## Ordering chat message events diff --git a/src/pages/docs/chat/rooms/presence.mdx b/src/pages/docs/chat/rooms/presence.mdx index 51ecc56a2d..50074573f3 100644 --- a/src/pages/docs/chat/rooms/presence.mdx +++ b/src/pages/docs/chat/rooms/presence.mdx @@ -101,13 +101,13 @@ The following are the properties of a presence event: | Property | Description | Type | | -------- | ----------- | ---- | -| type | The type of the event | String | -| member | The presence member that the event pertains to | PresenceMember | -| | `clientId`: The ID of the client that triggered the event. | String | -| | `connectionId`: The connection ID of the client that triggered the event. Use this in combination with `clientId` to identify a user across multiple devices. | String | -| | `data`: Optional user data. | Object | -| | `updatedAt`: The time that the event was emitted. | DateTime | -| | `extras`: A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads related to the user's latest presence event. | JSONObject(optional) | +| `type` | The type of the event | `String` | +| `member` | The presence member that the event pertains to | `PresenceMember` | +| `clientId` | The ID of the client that triggered the event. | `String` | +| `connectionId` | The connection ID of the client that triggered the event. Use this in combination with `clientId` to identify a user across multiple devices. | `String` | +| `data` | Optional user data. | `Object` | +| `updatedAt` | The time that the event was emitted. | `DateTime` | +| `extras` | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads related to the user's latest presence event. | `JSONObject`(optional) | ## Unsubscribe from presence @@ -460,7 +460,7 @@ The following options can be set when [creating a room](/docs/chat/rooms#create) | Property | Description | Default | | --- | --- | --- | -| enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling `presence.subscribe()` is still required. | true | +| `enableEvents` | Set whether the client has permissions to subscribe to the presence set. Calling `presence.subscribe()` is still required. | `true` | ## Retrieve the presence set @@ -529,13 +529,17 @@ val isPresent = room.presence.isUserPresent("client-id") Use the [`presenceData`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceListener.html#presenceData) property available from the response of the `usePresence` hook to view a list of all member's presence status in the room. + + ### Presence member structure The following are the properties of an individual presence member: | Property | Description | Type | | -------- | ----------- | ---- | -| clientId | The ID of the client this event relates to. | String | -| data | The latest optional user data associated with the user. | Object | -| extras | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads related to the user's latest presence event. | JsonObject (optional) | -| updatedAt | The time of the last presence event. | DateTime | +| `clientId` | The ID of the client this event relates to. | `String` | +| `data` | The latest optional user data associated with the user. | `Object` | +| `extras` | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads related to the user's latest presence event. | `JsonObject` (optional) | +| `updatedAt` | The time of the last presence event. | `DateTime` | diff --git a/src/pages/docs/chat/rooms/reactions.mdx b/src/pages/docs/chat/rooms/reactions.mdx index 0d2c8fd2e0..83cac1c8bb 100644 --- a/src/pages/docs/chat/rooms/reactions.mdx +++ b/src/pages/docs/chat/rooms/reactions.mdx @@ -214,3 +214,7 @@ fun SendReactionComponent(room: Room) { } ``` + + diff --git a/src/pages/docs/chat/rooms/replies.mdx b/src/pages/docs/chat/rooms/replies.mdx index 5f48a57a88..014bac6f89 100644 --- a/src/pages/docs/chat/rooms/replies.mdx +++ b/src/pages/docs/chat/rooms/replies.mdx @@ -136,6 +136,10 @@ fun SendReplyComponent(room: Room, messageToReplyTo: Message) { ``` + + ## Subscribe to message replies Message replies will be received as normal messages in the room using the [`subscribe()`](/docs/chat/rooms/messages#subscribe) method. diff --git a/src/pages/docs/chat/rooms/typing.mdx b/src/pages/docs/chat/rooms/typing.mdx index e16a28d269..d82a7fa150 100644 --- a/src/pages/docs/chat/rooms/typing.mdx +++ b/src/pages/docs/chat/rooms/typing.mdx @@ -99,11 +99,11 @@ The following are the properties of a typing event: | Property | Description | Type | |----------|-------------|------| -| type | The type of the event. | String | -| currentlyTyping | A set of all users currently typing. | Set | -| change | The single change that resulted in the event. | Object | -| | `type`: The type of change that occurred. | String | -| | `clientId`: The `clientId` of the user that triggered the change. | String | +| `type` | The type of the event. | `String` | +| `currentlyTyping` | A set of all users currently typing. | `Set` | +| `change` | The single change that resulted in the event. | `Object` | +| `type` | The type of change that occurred. | `String` | +| `clientId` | The `clientId` of the user that triggered the change. | `String` | You can use the size of the `currentlyTyping` set to decide whether to display individual user names, or that multiple people are typing in your user interface. diff --git a/src/pages/docs/chat/setup.mdx b/src/pages/docs/chat/setup.mdx index fd584e129f..6eb5f55be1 100644 --- a/src/pages/docs/chat/setup.mdx +++ b/src/pages/docs/chat/setup.mdx @@ -329,3 +329,7 @@ The `logLevel` sets the verbosity of logs that will be output by the SDK. The fo | warn | Anything that is not immediately an error, but could cause unexpected behavior in the future. For example, passing an invalid value to an option. Indicates that some action should be taken to prevent future errors. | | error | A given operation has failed and cannot be automatically recovered. The error may threaten the continuity of operation. | | silent | No logging will be performed. | + + diff --git a/src/pages/docs/guides/chat/build-livestream.mdx b/src/pages/docs/guides/chat/build-livestream.mdx index 72300d6d59..627c4cffba 100644 --- a/src/pages/docs/guides/chat/build-livestream.mdx +++ b/src/pages/docs/guides/chat/build-livestream.mdx @@ -25,6 +25,8 @@ Delivering chat messages in realtime is key to an engaging experience. Ably's [s Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable. Using features such as server-side batching and efficient connection management, along with Ably's consumption-based pricing model ensures costs are kept as low as possible, no matter the scale. + + ## Architecting your chat rooms: UX first, scale always The most important decision you can make when developing a livestream chat application is the experience you want users to have. This will determine the look and feel of the livestream and ultimately the impression your users leave with. @@ -69,6 +71,8 @@ Decisions that you need to make around throughput and rates: * For a large room chat scenario, we recommend a batching interval of **no more than 1 second**, which keeps the chat responsive but can still [significantly reduce costs](#server-side-batching). * For smaller groups and 1:1 chats, you may find that batching does not make a material difference to costs, but does affect the latency of the chat. In the rooms handling those chats, you may choose to not use batching. + + ## Authentication Authentication in livestream chat is a design decision. In some cases, you'll want to tie participants to their identity in your application. In others, anyone can join and participate. Ably Chat supports both of these scenarios - you don't need to go through the hassle of setting up users in Ably and trying to keep them in sync with your application. Every client has a `clientId`. If you want to allow random users, just use a random string. If you want to tie it to your application, then use the UUID of the user or some other well-known identifier. From f96c96533231357893454d6ecfd552a0545d4542 Mon Sep 17 00:00:00 2001 From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com> Date: Thu, 22 Jan 2026 13:31:06 +0100 Subject: [PATCH 2/2] Remove USP asides from table formatting branch --- src/pages/docs/chat/connect.mdx | 16 ++--- src/pages/docs/chat/rooms/history.mdx | 20 +++---- src/pages/docs/chat/rooms/index.mdx | 18 +++--- .../docs/chat/rooms/message-reactions.mdx | 4 -- src/pages/docs/chat/rooms/messages.mdx | 60 +++++++++---------- src/pages/docs/chat/rooms/occupancy.mdx | 20 +++---- src/pages/docs/chat/rooms/presence.mdx | 13 ++-- src/pages/docs/chat/rooms/reactions.mdx | 19 +++--- src/pages/docs/chat/rooms/replies.mdx | 4 -- src/pages/docs/chat/rooms/typing.mdx | 4 +- src/pages/docs/chat/setup.mdx | 25 ++++---- .../docs/guides/chat/build-livestream.mdx | 4 -- 12 files changed, 93 insertions(+), 114 deletions(-) diff --git a/src/pages/docs/chat/connect.mdx b/src/pages/docs/chat/connect.mdx index 044d6e3f69..24553bd74f 100644 --- a/src/pages/docs/chat/connect.mdx +++ b/src/pages/docs/chat/connect.mdx @@ -11,14 +11,14 @@ A connection can have any of the following statuses: | Status | Description | |--------|-------------| -| initialized | A connection object has been initialized but not yet connected. | -| connecting | A connection attempt has been initiated, this status is entered as soon as the SDK has completed initialization, and is re-entered each time connection is re-attempted following disconnection. | -| connected | A connection exists and is active. | -| disconnected | A temporary failure condition when no current connection exists. The disconnected status is entered if an established connection is dropped, or if a connection attempt is unsuccessful. | -| suspended | A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended status is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended status, an SDK will periodically attempt to open a new connection every 30 seconds. Rooms will be reattached on a successful reconnection, however message history will not be automatically recovered. | -| closing | An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection is forcibly terminated and the connection status becomes Closed. | -| closed | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically. No connection state is preserved by the service or the library. | -| failed | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. | +| `initialized` | A connection object has been initialized but not yet connected. | +| `connecting` | A connection attempt has been initiated, this status is entered as soon as the SDK has completed initialization, and is re-entered each time connection is re-attempted following disconnection. | +| `connected` | A connection exists and is active. | +| `disconnected` | A temporary failure condition when no current connection exists. The disconnected status is entered if an established connection is dropped, or if a connection attempt is unsuccessful. | +| `suspended` | A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended status is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended status, an SDK will periodically attempt to open a new connection every 30 seconds. Rooms will be reattached on a successful reconnection, however message history will not be automatically recovered. | +| `closing` | An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection is forcibly terminated and the connection status becomes Closed. | +| `closed` | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically. No connection state is preserved by the service or the library. | +| `failed` | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. | Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html) property to check which status a connection is currently in: diff --git a/src/pages/docs/chat/rooms/history.mdx b/src/pages/docs/chat/rooms/history.mdx index 9ab4d50487..6c1c616acb 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -3,12 +3,12 @@ title: Message storage and history meta_description: "Retrieve previously sent messages from history." --- -The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 30 days by default. You can extend this up to 365 days by [contacting us](https://ably.com/support). +The history feature enables users to retrieve messages that have been previously sent in a room. [Message persistence](/docs/chat/rooms#persistence) is enabled by default for all chat rooms, with messages stored for 30 days. You can extend this retention period up to 365 days by [contacting us](https://ably.com/support). ## Retrieve previously sent messages - -Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. + +Use the [`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#history)[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/history(withparams:))[`messages.history()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-messages/history.html) method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages. @@ -90,10 +90,10 @@ 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. | +| `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. | ## Retrieve messages sent prior to subscribing @@ -237,9 +237,9 @@ The following 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. | -| 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. | +| `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. | diff --git a/src/pages/docs/chat/rooms/index.mdx b/src/pages/docs/chat/rooms/index.mdx index 1cfec49d33..321ca0a08d 100644 --- a/src/pages/docs/chat/rooms/index.mdx +++ b/src/pages/docs/chat/rooms/index.mdx @@ -190,7 +190,7 @@ By default the `ChatRoomProvider` will automatically call [`release()`](https:// To start receiving messages and events from a room, you need to attach to it. Attaching to a room tells Ably to start streaming messages to the client, and ensures that events are not missed in case of temporary network interruptions. - + Once an instance of a room has been created using `rooms.get()`, clients attach to it to start receiving messages and events from the room. Use the [`attach()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#attach)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room/attach%28%29)[`attach()`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/attach.html) method on a room to attach to it: @@ -279,14 +279,14 @@ A room can have any of the following statuses: | Status | Description | | ------ | ----------- | -| initializing | The library is initializing the room. This status is only used for React when the room has not yet resolved. | -| initialized | The room has been initialized, but no attach has been attempted yet. | -| attaching | An attach has been initiated by sending a request to Ably. This is a transient status and will be followed either by a transition to attached, suspended, or failed. | -| attached | An attach has succeeded. In the attached status a client can publish and subscribe to messages, and enter the presence set. | -| detaching | A detach has been initiated on the attached room by sending a request to Ably. This is a transient status and will be followed either by a transition to detached or failed. | -| detached | The room has been detached by the client. | -| suspended | The room, having previously been attached, has lost continuity. This is normally due to the client being disconnected from Ably for more than two minutes. The client will automatically attempt to reattach as soon as connectivity is restored. | -| failed | An indefinite failure condition. This status is entered if an error has been received from Ably, such as an attempt to attach without the necessary access rights. | +| `initializing` | The library is initializing the room. This status is only used for React when the room has not yet resolved. | +| `initialized` | The room has been initialized, but no attach has been attempted yet. | +| `attaching` | An attach has been initiated by sending a request to Ably. This is a transient status and will be followed either by a transition to attached, suspended, or failed. | +| `attached` | An attach has succeeded. In the attached status a client can publish and subscribe to messages, and enter the presence set. | +| `detaching` | A detach has been initiated on the attached room by sending a request to Ably. This is a transient status and will be followed either by a transition to detached or failed. | +| `detached` | The room has been detached by the client. | +| `suspended` | The room, having previously been attached, has lost continuity. This is normally due to the client being disconnected from Ably for more than two minutes. The client will automatically attempt to reattach as soon as connectivity is restored. | +| `failed` | An indefinite failure condition. This status is entered if an error has been received from Ably, such as an attempt to attach without the necessary access rights. | Use the [`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#status)[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomstatus)[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/status.html) property to check which status a room is currently in: diff --git a/src/pages/docs/chat/rooms/message-reactions.mdx b/src/pages/docs/chat/rooms/message-reactions.mdx index 38206b50e3..57d86dcd11 100644 --- a/src/pages/docs/chat/rooms/message-reactions.mdx +++ b/src/pages/docs/chat/rooms/message-reactions.mdx @@ -394,10 +394,6 @@ fun RemoveMessageReactionComponent(room: Room, message: Message) { ``` - - ## Messages and reactions The `Message` object contains a `reactions` property which is an object that looks like this: diff --git a/src/pages/docs/chat/rooms/messages.mdx b/src/pages/docs/chat/rooms/messages.mdx index 776376a170..c511a13f78 100644 --- a/src/pages/docs/chat/rooms/messages.mdx +++ b/src/pages/docs/chat/rooms/messages.mdx @@ -104,19 +104,19 @@ The following are the properties of a message: | Property | Description | Type | | -------- | ----------- | ---- | -| `serial` | An Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages. | `string` | -| `clientId` | The client identifier of the user that created the message. | `string` | -| `text` | The message contents. | `string` | -| `headers` | Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. | `object` | -| `metadata` | Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. | `object` | -| `timestamp` | The time the message was created. | `date` | -| `action` | The latest action performed on this message, such as `message.create`, `message.update` or `message.delete`. | `string` | -| `version` | Contains information about the current version of the message. For `message.create` actions, only `serial` and `timestamp` are set. For `message.update` and `message.delete` actions, additional fields are included. | `object` | -| `serial`| An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version.serial` is identical to `serial` if the action is `message.create`. | `string` | -| `timestamp` | The time the action was performed. It will be identical to `timestamp` if the action is a `message.create`. | `date` | -| `clientId` | The client identifier of the user that created this version of the message. Only set for `message.update` and `message.delete` actions. | `string` or `undefined` | -| `description` | Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `string` or `undefined` | -| `metadata` | Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `object` or `undefined` | +| `serial` | An Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages. | `String` | +| `clientId` | The client identifier of the user that created the message. | `String` | +| `text` | The message contents. | `String` | +| `headers` | Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. | `Object` | +| `metadata` | Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. | `Object` | +| `timestamp` | The time the message was created. | `Date` | +| `action` | The latest action performed on this message, such as `message.create`, `message.update` or `message.delete`. | `String` | +| `version` | Contains information about the current version of the message. For `message.create` actions, only `serial` and `timestamp` are set. For `message.update` and `message.delete` actions, additional fields are included. | `Object` | +| `version.serial` | An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version.serial` is identical to `serial` if the action is `message.create`. | `String` | +| `version.timestamp` | The time the action was performed. It will be identical to `timestamp` if the action is a `message.create`. | `Date` | +| `version.clientId` | The client identifier of the user that created this version of the message. Only set for `message.update` and `message.delete` actions. | `String` or `undefined` | +| `version.description` | Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `String` or `undefined` | +| `version.metadata` | Optional metadata provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | `Object` or `undefined` | See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application. @@ -524,13 +524,13 @@ The updated message response is identical to the structure of a message, with th | Property | Description | Type | | -------- | ----------- | ---- | -| `action` | Set to `message.update`. | `string` | -| `version` | Contains additional fields compared to `message.create` action: | `object` | -| `serial`| Set to the serial of the update action. | `string` | -| `timestamp` | Set to the time the message was updated. | `date` | -| `clientId` | The client identifier of the user who performed the update. | `string` or `undefined` | -| `description` | Optional description provided in the update request. | `string` or `undefined` | -| `metadata` | Optional metadata provided in the update request. | `object` or `undefined` | +| `action` | Set to `message.update`. | `String` | +| `version` | Contains additional fields compared to `message.create` action: | `Object` | +| `version.serial` | Set to the serial of the update action. | `String` | +| `version.timestamp` | Set to the time the message was updated. | `Date` | +| `version.clientId` | The client identifier of the user who performed the update. | `String` or `undefined` | +| `version.description` | Optional description provided in the update request. | `String` or `undefined` | +| `version.metadata` | Optional metadata provided in the update request. | `Object` or `undefined` | ## Delete a message @@ -774,16 +774,16 @@ The deleted message response is identical to the structure of a message, with th | Property | Description | Type | | -------- | ----------- | ---- | -| `action` | Set to `message.delete`. | `string` | -| `version` | Contains additional fields compared to `message.create` action: | `object` | -| `serial` | Set to the serial of the deletion action. | `string` | -| `timestamp` | Set to the time the message was deleted. | `date` | -| `clientId` | The client identifier of the user who performed the deletion. | `string` or `undefined` | -| `description` | Optional description provided in the delete request. | `string` or `undefined` | -| `metadata` | Optional metadata provided in the delete request. | `object` or `undefined` | -| `text` | Set to the empty string. | `string` | -| `metadata` | Set to the empty object. | `object` | -| `headers` | Set to the empty object. | `object` | +| `action` | Set to `message.delete`. | `String` | +| `version` | Contains additional fields compared to `message.create` action: | `Object` | +| `version.serial` | Set to the serial of the deletion action. | `String` | +| `version.timestamp` | Set to the time the message was deleted. | `Date` | +| `version.clientId` | The client identifier of the user who performed the deletion. | `String` or `undefined` | +| `version.description` | Optional description provided in the delete request. | `String` or `undefined` | +| `version.metadata` | Optional metadata provided in the delete request. | `Object` or `undefined` | +| `text` | Set to the empty string. | `String` | +| `metadata` | Set to the empty object. | `Object` | +| `headers` | Set to the empty object. | `Object` | ## Ordering chat message events diff --git a/src/pages/docs/chat/rooms/occupancy.mdx b/src/pages/docs/chat/rooms/occupancy.mdx index b789286436..fcfec67a71 100644 --- a/src/pages/docs/chat/rooms/occupancy.mdx +++ b/src/pages/docs/chat/rooms/occupancy.mdx @@ -119,10 +119,10 @@ The following are the properties of an occupancy event: | Property | Description | Type | | -------- | ----------- | ---- | -| type | The type of the occupancy event. | String | -| occupancy | The occupancy data for the room. | OccupancyData | -| | `connections`: The number of connections in the room. | Number | -| | `presenceMembers`: The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | Number | +| `type` | The type of the occupancy event. | `String` | +| `occupancy` | The occupancy data for the room. | `OccupancyData` | +| `occupancy.connections` | The number of connections in the room. | `Number` | +| `occupancy.presenceMembers` | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | `Number` | @@ -130,8 +130,8 @@ The following are the properties of an occupancy event: | Property | Description | Type | | -------- | ----------- | ---- | -| connections | The number of connections in the room. | Number | -| presenceMembers | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | Number | +| `connections` | The number of connections in the room. | `Number` | +| `presenceMembers` | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | `Number` | @@ -229,8 +229,8 @@ The following are the properties of the occupancy data: | Property | Description | Type | | -------- | ----------- | ---- | -| connections | The number of connections in the room. | Number | -| presenceMembers | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | Number | +| `connections` | The number of connections in the room. | `Number` | +| `presenceMembers` | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | `Number` | ## Retrieve room occupancy @@ -277,8 +277,8 @@ The following are the properties of an occupancy data: | Property | Description | Type | | -------- | ----------- | ---- | -| connections | The number of connections in the room. | Number | -| presenceMembers | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | Number | +| `connections` | The number of connections in the room. | `Number` | +| `presenceMembers` | The number of users entered into the [presence set](/docs/chat/rooms/presence) of the room. | `Number` |