Skip to content

Table formatting improvements (chat) #3145

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

Merged
GregHolmes merged 2 commits into from
Jan 28, 2026
Merged

Table formatting improvements (chat) #3145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2d12da7
Addresses feedback from review
franrob-projects Jan 21, 2026
f96c965
Remove USP asides from table formatting branch
franrob-projects Jan 22, 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
16 changes: 8 additions & 8 deletions src/pages/docs/chat/connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

<If lang="javascript,swift,kotlin,jetpack">
Use the <If lang="javascript">[`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)</If><If lang="swift">[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)</If><If lang="kotlin,jetpack">[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html)</If> property to check which status a connection is currently in:
Expand Down
14 changes: 7 additions & 7 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 @@ -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 <a id="subscribe"/>

Expand Down Expand Up @@ -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. |

<If lang="jetpack">

Expand Down
16 changes: 8 additions & 8 deletions src/pages/docs/chat/rooms/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

<If lang="javascript,swift,kotlin,jetpack">
Use the <If lang="javascript">[`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomStatus.html#status)</If><If lang="swift">[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomstatus)</If><If lang="kotlin,jetpack">[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-room/status.html)</If> property to check which status a room is currently in:
Expand Down
60 changes: 30 additions & 30 deletions src/pages/docs/chat/rooms/messages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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 <a id="delete"/>

Expand Down Expand Up @@ -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 <a id="global-ordering"/>

Expand Down
Loading