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 d95a33b22e..6c1c616acb 100644 --- a/src/pages/docs/chat/rooms/history.mdx +++ b/src/pages/docs/chat/rooms/history.mdx @@ -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 616f5aba81..321ca0a08d 100644 --- a/src/pages/docs/chat/rooms/index.mdx +++ b/src/pages/docs/chat/rooms/index.mdx @@ -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/messages.mdx b/src/pages/docs/chat/rooms/messages.mdx index afd3dd37e7..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` |