From d2a47fe1c50e59e6ddf0e94fd0ba1a6a92825adb Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:13:38 +0000 Subject: [PATCH 01/13] Add Chat Kotlin API reference pages to navigation Add navigation entries for all 11 Kotlin Chat API reference pages, replacing the external Dokka SDK link with inline page links mirroring the JavaScript API reference structure. Co-Authored-By: Claude Opus 4.6 --- src/data/nav/chat.ts | 50 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/src/data/nav/chat.ts b/src/data/nav/chat.ts index af612eee13..406ec76c8c 100644 --- a/src/data/nav/chat.ts +++ b/src/data/nav/chat.ts @@ -300,9 +300,53 @@ export default { external: true, }, { - link: 'https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/', - name: 'Kotlin SDK', - external: true, + name: 'Kotlin', + pages: [ + { + link: '/docs/chat/api/kotlin/chat-client', + name: 'ChatClient', + }, + { + link: '/docs/chat/api/kotlin/connection', + name: 'Connection', + }, + { + link: '/docs/chat/api/kotlin/rooms', + name: 'Rooms', + }, + { + link: '/docs/chat/api/kotlin/room', + name: 'Room', + }, + { + link: '/docs/chat/api/kotlin/messages', + name: 'Messages', + }, + { + link: '/docs/chat/api/kotlin/message', + name: 'Message', + }, + { + link: '/docs/chat/api/kotlin/message-reactions', + name: 'MessageReactions', + }, + { + link: '/docs/chat/api/kotlin/presence', + name: 'Presence', + }, + { + link: '/docs/chat/api/kotlin/occupancy', + name: 'Occupancy', + }, + { + link: '/docs/chat/api/kotlin/typing', + name: 'Typing', + }, + { + link: '/docs/chat/api/kotlin/room-reactions', + name: 'RoomReactions', + }, + ], }, { link: 'https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/', From 6dd9662cc816b989a26bd28bb975ce3f57540667 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:13:44 +0000 Subject: [PATCH 02/13] Review and update Chat Kotlin ChatClient API reference Add ChatException section, experimental annotations on realtime and stateDispatcher properties, Required column consistency for param tables, and DSL builder overload method signature. Co-Authored-By: Claude Opus 4.6 --- .../docs/chat/api/kotlin/chat-client.mdx | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/chat-client.mdx diff --git a/src/pages/docs/chat/api/kotlin/chat-client.mdx b/src/pages/docs/chat/api/kotlin/chat-client.mdx new file mode 100644 index 0000000000..22d17f7228 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/chat-client.mdx @@ -0,0 +1,189 @@ +--- +title: ChatClient +meta_description: "API reference for the ChatClient interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, ChatClient API, constructor, rooms, connection, clientId, realtime" +--- + +The `ChatClient` interface is the main entry point for using the Ably Chat SDK. It provides access to chat rooms, connection management, and the underlying Ably Realtime client. + +The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably. Instantiate a realtime client using the Pub/Sub SDK and pass the generated client into the Chat factory function. + + +```kotlin +import com.ably.chat.ChatClient +import com.ably.chat.LogLevel + +val realtimeClient = createRealtimeClient { + key = "{{API_KEY}}" + clientId = "" +} +val chatClient = ChatClient(realtimeClient) { + logLevel = LogLevel.Error +} +``` + + +An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using [JWT authentication](/docs/auth/token#jwt). + + + +## Properties + +The `ChatClient` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| rooms | The rooms object, used to get or create chat room instances. | [Rooms](/docs/chat/api/kotlin/rooms) | +| connection | The connection object, used to monitor the connection status with Ably. | [Connection](/docs/chat/api/kotlin/connection) | +| clientId | The client ID configured on the underlying Ably Realtime client. Used to identify the current user. May be `null` until authenticated with a token. | String | +| realtime | The underlying Ably Realtime client instance. Note: this property is experimental and may change in a future release. | RealtimeClient | +| clientOptions | The resolved configuration options with defaults applied. |
| + +
+ + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| logLevel | Optional | The logging level to use. Default: `LogLevel.Error`. | | +| logHandler | Optional | A custom log handler function that receives log messages from the SDK. | `((LogEntry) -> Unit)?` | +| stateDispatcher | Optional | The coroutine dispatcher used for managing state updates within the chat client. Allows controlling concurrency and dispatching of state management tasks. Note: this property is experimental and may change in a future release. | `CoroutineDispatcher` | + +
+ + + +| Value | Description | +| --- | --- | +| Trace | Log all messages. | +| Debug | Log debug, info, warn, and error messages. | +| Info | Log info, warn, and error messages. | +| Warn | Log warn and error messages. | +| Error | Log error messages only. | +| Silent | Disable logging. | + + + +## Create a chat client + +{`ChatClient(realtimeClient: RealtimeClient, clientOptions: ChatClientOptions = buildChatClientOptions()): ChatClient`} + +Create a new `ChatClient` instance by passing an Ably Realtime client and optional configuration options. `ChatClient` is a top-level factory function, not a class constructor. + + +```kotlin +import com.ably.chat.ChatClient +import com.ably.chat.buildChatClientOptions +import com.ably.chat.LogLevel + +val realtimeClient = createRealtimeClient { + key = "{{API_KEY}}" + clientId = "user-123" +} + +val chatClient = ChatClient(realtimeClient, buildChatClientOptions { + logLevel = LogLevel.Debug +}) +``` + + +A DSL builder overload is also available: + +{`ChatClient(realtimeClient: RealtimeClient, init: MutableChatClientOptions.() -> Unit): ChatClient`} + + +```kotlin +val chatClient = ChatClient(realtimeClient) { + logLevel = LogLevel.Debug +} +``` + + +### Parameters + +The `ChatClient()` factory function takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| realtimeClient | Required | An instance of the Ably Realtime client, configured with your API key and a `clientId`. The `clientId` is required for all chat operations. | RealtimeClient | +| clientOptions | Optional | Configuration options for the Chat client. |
| + +
+ +## ChatException + +A specialized exception class for errors that occur during chat operations. `ChatException` extends `RuntimeException` and wraps an [`ErrorInfo`](#errorinfo) object containing detailed error information. All suspend functions in the SDK throw `ChatException` on failure. + + + +| Property | Description | Type | +| --- | --- | --- | +| errorInfo | Detailed error information including Ably-specific error codes and HTTP status codes. | [ErrorInfo](#errorinfo) | +| message | The exception message, or `null`. | String | +| cause | The underlying cause of the exception, if any, or `null`. | Throwable | + +
+ + +```kotlin +import com.ably.chat.ChatException + +try { + room.messages.send(text = "Hello!") +} catch (e: ChatException) { + println("Error code: ${e.errorInfo.code}") + println("Message: ${e.errorInfo.message}") + println("Status: ${e.errorInfo.statusCode}") +} +``` + + +## ErrorInfo + +A standardized, generic Ably error object that contains an Ably-specific status code, and a generic HTTP status code. All errors thrown by the SDK are compatible with the `ErrorInfo` structure. + + + +| Property | Description | Type | +| --- | --- | --- | +| code | Ably-specific error code. | Int | +| statusCode | HTTP status code corresponding to this error, where applicable. | Int | +| message | Additional information about the error. | String | +| href | A URL providing more information about the error, or `null`. | String | +| cause | The underlying cause of the error, or `null`. | ErrorInfo | +| requestId | The request ID if the error originated from an API request, or `null`. | String | + +
+ +## Example + + +```kotlin +import com.ably.chat.ChatClient +import com.ably.chat.LogLevel + +val realtimeClient = createRealtimeClient { + key = "{{API_KEY}}" + clientId = "user-123" +} + +val chatClient = ChatClient(realtimeClient) { + logLevel = LogLevel.Debug +} + +// Access rooms +val room = chatClient.rooms.get("my-room") + +// Check connection status +println(chatClient.connection.status) + +// Get current user ID +println(chatClient.clientId) +``` + From a0b669bced55ebd43aaa943cd79afeb32c924c66 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:13:48 +0000 Subject: [PATCH 03/13] Review and update Chat Kotlin Rooms API reference Add DSL builder overload method signature for rooms.get() and apply Required column consistency to parameter tables. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/rooms.mdx | 186 +++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/rooms.mdx diff --git a/src/pages/docs/chat/api/kotlin/rooms.mdx b/src/pages/docs/chat/api/kotlin/rooms.mdx new file mode 100644 index 0000000000..f390f2e76c --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/rooms.mdx @@ -0,0 +1,186 @@ +--- +title: Rooms +meta_description: "API reference for the Rooms interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Rooms API, get, release, RoomOptions, buildRoomOptions" +--- + +The `Rooms` interface manages the lifecycle of chat rooms. + +Access it via the `rooms` property on a [`ChatClient`](/docs/chat/api/kotlin/chat-client) instance. + + +```kotlin +val rooms = chatClient.rooms +``` + + +## Create or retrieve a room + +{`suspend rooms.get(name: String, options: RoomOptions = buildRoomOptions()): Room`} + +Create or retrieve a [`Room`](/docs/chat/api/kotlin/room) instance. Optionally provide custom configuration to the room. + +Call [`release()`](#release) when the `Room` is no longer needed. If a call to `get()` is made for a room that is currently being released, then it will only return when the release operation is complete. + +If a call to `get()` is made, followed by a subsequent call to `release()` before it returns, then an error is thrown. + + +```kotlin +val room = chatClient.rooms.get( + name = "basketball-stream", + options = buildRoomOptions { + typing { + heartbeatThrottle = 5.seconds + } + presence { + enableEvents = false + } + occupancy { + enableEvents = true + } + messages { + rawMessageReactions = false + defaultMessageReactionType = MessageReactionType.Unique + } + } +) + +// When finished with the room +chatClient.rooms.release("basketball-stream") +``` + + +A DSL builder overload is also available: + +{`suspend rooms.get(roomName: String, initOptions: MutableRoomOptions.() -> Unit): Room`} + + +```kotlin +val room = chatClient.rooms.get("basketball-stream") { + typing { + heartbeatThrottle = 5.seconds + } + occupancy { + enableEvents = true + } +} +``` + + +### Parameters + +The `get()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| name | Required | The unique identifier of the room. | String | +| options | Optional | Configuration for the room features. |
| + +
+ + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| typing | Optional | Configuration for typing indicators. | | +| presence | Optional | Configuration for presence events. |
| +| occupancy | Optional | Configuration for occupancy events. |
| +| messages | Optional | Configuration for message reactions. |
| +| reactions | Optional | Configuration for room reactions. | RoomReactionsOptions | + +
+ + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| heartbeatThrottle | Optional | Minimum time between consecutive typing started events. The first call emits immediately; later calls are no-ops until the interval has elapsed. Calling `typing.stop()` resets the interval. Default 10 seconds. | `Duration` | + + + + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| enableEvents | Optional | Whether the client receives presence events from the server. Can be disabled if presence is used but this client does not need the messages. Default `true`. | Boolean | + + + + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| enableEvents | Optional | Whether to receive occupancy events. Enabling this increases message volume as the server sends additional updates for occupancy changes. Default `false`. | Boolean | + + + + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| rawMessageReactions | Optional | Whether to receive raw individual message reactions from the realtime channel. Reaction summaries remain available regardless of this setting. Default `false`. | Boolean | +| defaultMessageReactionType | Optional | The default message reaction type for sending reactions. Individual types can still be specified via the send method parameter. The default is `Distinct`. | | + +
+ + + +| Value | Description | +| --- | --- | +| Distinct | Allows at most one reaction of each type per client per message. Duplicates are not counted in the summary. Similar to reactions on Slack. | +| Multiple | Allows any number of reactions, including repeats, counted in the summary. The reaction payload includes a count. Similar to the clap feature on Medium. | +| Unique | Allows at most one reaction per client per message. If a client reacts again, only the second reaction is counted. Similar to reactions on iMessage or WhatsApp. | + + + +### Returns + +[`Room`](/docs/chat/api/kotlin/room) + +This is a suspend function. It returns the new or existing [`Room`](/docs/chat/api/kotlin/room) instance, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo). It also throws if the room already exists with different options, or if [`release()`](#release) is called before `get()` returns. + +## Release a room + +{`suspend rooms.release(name: String): Unit`} + +Releases a room, freeing its resources and detaching it from Ably. + +After release, the room object is no longer usable. To use the room again, call [`get()`](#get) to create a new instance. + + +```kotlin +chatClient.rooms.release("my-room") +``` + + +### Parameters + +The `release()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| name | Required | The unique identifier of the room to release. | String | + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the room is fully released, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscription + +A `Subscription` is a functional interface returned by `subscribe()` and `onStatusChange()` methods throughout the SDK. It provides a single method to deregister the listener. + + + +| Method | Description | Return type | +| --- | --- | --- | +| unsubscribe() | Deregisters the listener. | Unit | + +
From 7c94a6083a59eb2c81712e438a104fd2b872086a Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:13:54 +0000 Subject: [PATCH 04/13] Review and update Chat Kotlin Room API reference Add experimental channel property, convert property tables to use description-based nullability instead of Required column for interface properties. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/room.mdx | 305 ++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/room.mdx diff --git a/src/pages/docs/chat/api/kotlin/room.mdx b/src/pages/docs/chat/api/kotlin/room.mdx new file mode 100644 index 0000000000..c3a20dce9c --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/room.mdx @@ -0,0 +1,305 @@ +--- +title: Room +meta_description: "API reference for the Room interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Room API, attach, detach, onStatusChange, onDiscontinuity, statusAsFlow, discontinuityAsFlow, messages, presence, typing, occupancy, reactions" +--- + +The `Room` interface represents an individual chat room instance. It provides access to all chat features such as messages, presence, reactions, typing indicators, and occupancy. Rooms are the primary way users interact with chat functionality. + +## Obtaining a room instance + +Use the [`rooms.get()`](/docs/chat/api/kotlin/rooms#get) method to obtain a room instance: + + +```kotlin +val room = chatClient.rooms.get("my-room") +``` + + +For more information, see the [rooms documentation](/docs/chat/rooms). + +## Properties + +The `Room` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| name | The unique identifier of the room. | String | +| messages | The Messages instance for sending and receiving messages. | [Messages](/docs/chat/api/kotlin/messages) | +| presence | The Presence instance for tracking online users. | [Presence](/docs/chat/api/kotlin/presence) | +| reactions | The RoomReactions instance for room-level reactions. | [RoomReactions](/docs/chat/api/kotlin/room-reactions) | +| typing | The Typing instance for typing indicators. | [Typing](/docs/chat/api/kotlin/typing) | +| occupancy | The Occupancy instance for tracking user counts. | [Occupancy](/docs/chat/api/kotlin/occupancy) | +| status | The current lifecycle status of the room. |
| +| error | The error information if the room is in a failed state, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | +| options | The resolved configuration options for this room. | [RoomOptions](/docs/chat/api/kotlin/rooms#get) | +| channel | The underlying Ably channel used for the room. Note: this property is experimental and may change in a future release. | RealtimeChannel | + +
+ + + +| Status | Description | +| --- | --- | +| 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 by a transition to `Attached`, `Suspended`, or `Failed`. | +| Attached | The room is attached and actively receiving events. In this status, clients 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 by a transition to `Detached` or `Failed`. | +| Detached | The room has been detached by the client and is no longer receiving events. | +| Suspended | The room, having previously been attached, has lost continuity. This typically occurs when the client is disconnected from Ably for more than two minutes. The client will automatically attempt to reattach when connectivity is restored. | +| Failed | An indefinite failure condition. This status is entered if an error is received from Ably, such as an attempt to attach without the necessary access rights. | +| Releasing | The room is being released and its resources are being cleaned up. Attempting to use a room in this state may result in undefined behavior. | +| Released | The room has been released and is no longer usable. A new room instance must be obtained to continue using the room. | + + + +## Attach to a room + +{`suspend room.attach(): Unit`} + +Attach to the room to start receiving messages and events. Attaching is required before the client can publish or subscribe to room events. + + +```kotlin +room.attach() +``` + + +### Returns + +`Unit` + +This is a suspend function. It completes when the room is attached, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +For more information, see [attach to a room](/docs/chat/rooms#attach). + +## Detach from a room + +{`suspend room.detach(): Unit`} + +Detach from the room to stop receiving messages and events. Existing subscriptions are preserved but will not receive events until the room is re-attached. + + +```kotlin +room.detach() +``` + + +### Returns + +`Unit` + +This is a suspend function. It completes when the room is detached, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +For more information, see [detach from a room](/docs/chat/rooms#detach). + +## Subscribe to room status changes + +{`room.onStatusChange(listener: RoomStatusListener): Subscription`} + +Register a listener to receive room status change events. The listener is called whenever the room transitions between lifecycle states. + + +```kotlin +val subscription = room.onStatusChange { change -> + println("Room status changed to: ${change.current}") + change.error?.let { error -> + println("Error: $error") + } +} + +// To remove the listener +subscription.unsubscribe() +``` + + +### Parameters + +The `onStatusChange()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | A function that receives status change events. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| current | The new status of the room. | | +| previous | The previous status of the room. |
| +| error | An error that provides a reason why the room has entered the new status, if applicable, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | + +
+ +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Deregister the listener + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to deregister the room status listener. + +## Subscribe to discontinuity events + +{`room.onDiscontinuity(listener: DiscontinuityListener): Subscription`} + +Register a listener to detect connection interruptions and potentially missed events. This is useful for understanding when the client may have missed messages due to connectivity issues. + + +```kotlin +val subscription = room.onDiscontinuity { reason -> + println("Discontinuity detected: $reason") + // You may want to re-fetch recent messages here +} + +// To remove the listener +subscription.unsubscribe() +``` + + +### Parameters + +The `onDiscontinuity()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | A function that receives discontinuity events. |
| + +
+ + + +| Parameter | Description | Type | +| --- | --- | --- | +| error | An error providing context about why the discontinuity occurred. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | + + + +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Deregister the listener + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to deregister the discontinuity listener. + +## Collect room status changes as a Flow + +{`Room.statusAsFlow(): Flow`} + +Returns a Kotlin `Flow` that emits room status changes. This is an extension function on the `Room` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.statusAsFlow().collect { change -> + println("Room status: ${change.current}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `RoomStatusChange` events. The flow automatically manages the underlying subscription. + +## Collect discontinuity events as a Flow + +{`Room.discontinuityAsFlow(): Flow`} + +Returns a Kotlin `Flow` that emits discontinuity events. This is an extension function on the `Room` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.discontinuityAsFlow().collect { error -> + println("Discontinuity detected: $error") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `ErrorInfo` events when discontinuities occur. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.RoomStatus +import com.ably.chat.statusAsFlow +import com.ably.chat.discontinuityAsFlow +import kotlinx.coroutines.launch + +val room = chatClient.rooms.get("my-room") + +// Attach to start receiving events +room.attach() + +// Monitor room status with a listener +val statusSub = room.onStatusChange { change -> + println("Room status: ${change.current}") +} + +// Monitor for discontinuities +val discSub = room.onDiscontinuity { reason -> + println("Discontinuity detected, consider re-fetching messages") +} + +// Or use Flow for reactive collection +launch { + room.statusAsFlow().collect { change -> + when (change.current) { + RoomStatus.Attached -> println("Room attached") + RoomStatus.Suspended -> println("Room suspended") + RoomStatus.Failed -> println("Room failed: ${change.error}") + else -> {} + } + } +} + +launch { + room.discontinuityAsFlow().collect { error -> + println("Discontinuity: $error") + } +} + +// Access room features +val messages = room.messages +val presence = room.presence +val typing = room.typing + +// Get the room name +println("Room name: ${room.name}") + +// When done, detach and clean up +room.detach() +statusSub.unsubscribe() +discSub.unsubscribe() +``` + From d94831b701918b138d772bda17009ee4ce70f2fb Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:13:58 +0000 Subject: [PATCH 05/13] Review and update Chat Kotlin Messages API reference Add extension function overload signatures for update() and delete(), remove nullable type syntax from parameter tables. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/messages.mdx | 458 ++++++++++++++++++++ 1 file changed, 458 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/messages.mdx diff --git a/src/pages/docs/chat/api/kotlin/messages.mdx b/src/pages/docs/chat/api/kotlin/messages.mdx new file mode 100644 index 0000000000..f97ee8590a --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/messages.mdx @@ -0,0 +1,458 @@ +--- +title: Messages +meta_description: "API reference for the Messages interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Messages API, subscribe, send, history, get, update, delete, asFlow, chat messages" +--- + +The `Messages` interface provides methods for sending, receiving, and managing chat messages in a room. Access it via `room.messages`. + + +```kotlin +val messages = room.messages +``` + + +## Properties + +The `Messages` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| reactions | Access to message reactions functionality for adding, removing, and subscribing to reactions on specific messages. | [MessageReactions](/docs/chat/api/kotlin/message-reactions) | + +
+ +## Subscribe to messages + +{`messages.subscribe(listener: MessageListener): MessagesSubscription`} + +Subscribe to chat message events in the room. This method allows you to listen for new messages and provides access to historical messages that occurred before the subscription was established. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) for the listener to receive new message events. + + +```kotlin +val (unsubscribe, subscription) = room.messages.subscribe { event -> + println("Received message: ${event.message.text}") +} + +// Get messages sent before subscribing +val history = subscription.historyBeforeSubscribe() + +// To stop receiving messages +unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | A callback function invoked when chat message events occur. |
| + +
+ + + +| Parameter | Description | Type | +| --- | --- | --- | +| event | The message event that was received. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of the message event. | | +| message | The message that was received. | [Message](/docs/chat/api/kotlin/message) | + +
+ + + +| Value | Description | +| --- | --- | +| Created | A new chat message was received. | +| Updated | A chat message was updated. | +| Deleted | A chat message was deleted. | + + + +### Returns + +`MessagesSubscription` + +Returns a `MessagesSubscription` that extends [`Subscription`](/docs/chat/api/kotlin/rooms#Subscription). It supports destructuring into `(unsubscribe, subscription)`. + +#### Unsubscribe from messages + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop listening for message events. + +#### Get messages from before the subscription started + +{`suspend subscription.historyBeforeSubscribe(start: Long? = null, end: Long? = null, limit: Int = 100): PaginatedResult`} + +Get messages sent to the room from before the subscription was established. + +##### Parameters + +The `historyBeforeSubscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| start | Optional | Start of the time window to query, as a Unix timestamp in milliseconds. | Long | +| end | Optional | End of the time window to query, as a Unix timestamp in milliseconds. | Long | +| limit | Optional | Maximum number of messages to retrieve. Default: `100`. | Int | + +
+ +##### Returns + +[`PaginatedResult`](#PaginatedResult) + +This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Send a message + +{`suspend messages.send(text: String, metadata: JsonObject? = null, headers: Map? = null): Message`} + +Send a message to the chat room. The message will be delivered to all subscribers in real-time. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val message = room.messages.send(text = "Hello, world!") + +println("Message sent with serial: ${message.serial}") +``` + + +### Parameters + +The `send()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| text | Required | The text content of the message. | String | +| metadata | Optional | Extra information attached to the message for features like animations or linking to external resources. | `JsonObject` | +| headers | Optional | Additional information in Ably message extras, usable for features like livestream timestamping or message flagging. | `Map` | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +This is a suspend function. It returns the sent [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Get message history + +{`suspend messages.history(start: Long? = null, end: Long? = null, limit: Int = 100, orderBy: OrderBy = OrderBy.NewestFirst): PaginatedResult`} + +Get messages that have been previously sent to the chat room. This method retrieves historical messages based on the provided query options, allowing you to paginate through message history, filter by time ranges, and control the order of results. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val history = room.messages.history( + limit = 50, + orderBy = OrderBy.NewestFirst +) + +println("Messages: ${history.items}") + +// Get next page if available +if (history.hasNext()) { + val nextPage = history.next() +} +``` + + +### Parameters + +The `history()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| start | Optional | Start of the time window to query, as a Unix timestamp in milliseconds. | Long | +| end | Optional | End of the time window to query, as a Unix timestamp in milliseconds. | Long | +| limit | Optional | Maximum number of messages to retrieve. Default: `100`. | Int | +| orderBy | Optional | Order in which to return results. Default: `NewestFirst`. |
| + +
+ + + +| Value | Description | +| --- | --- | +| OldestFirst | Return results starting with the oldest messages. | +| NewestFirst | Return results starting with the newest messages. | + + + +### Returns + +[`PaginatedResult`](#PaginatedResult) + +This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Get a specific message + +{`suspend messages.get(serial: String): Message`} + +Get a specific message by its unique serial identifier. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val message = room.messages.get("01234567890@abcdefghij") +println("Message text: ${message.text}") +``` + + +### Parameters + +The `get()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| serial | Required | The unique serial identifier of the message to retrieve. | String | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +This is a suspend function. It returns the [Message](/docs/chat/api/kotlin/message) object matching the given serial, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Update a message + +{`suspend messages.update(serial: String, text: String, metadata: JsonObject? = null, headers: Map? = null, operationDescription: String? = null, operationMetadata: Map? = null): Message`} + +Update a message in the chat room. This method modifies an existing message's content, metadata, or headers. The update creates a new version of the message while preserving the original serial identifier. Subscribers will receive an update event in real-time. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val updatedMessage = room.messages.update( + serial = message.serial, + text = "Updated message text", + operationDescription = "Fixed typo" +) + +println("Message updated: ${updatedMessage.version}") +``` + + +An extension function overload is also available that accepts a `Message` object directly: + +{`suspend Messages.update(updatedMessage: Message, operationDescription: String? = null, operationMetadata: Map? = null): Message`} + + +```kotlin +val updatedMessage = room.messages.update( + updatedMessage = message.copy(text = "Updated text"), + operationDescription = "Fixed typo" +) +``` + + +### Parameters + +The `update()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| serial | Required | The unique identifier of the message to update. | String | +| text | Required | The new text content of the message. | String | +| metadata | Optional | New metadata for the message. | `JsonObject` | +| headers | Optional | New headers for the message. | `Map` | +| operationDescription | Optional | A human-readable description of why the update was performed. | String | +| operationMetadata | Optional | Additional metadata about the operation. Do not use for authoritative information. | `Map` | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +This is a suspend function. It returns the updated [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. The returned message will have its `action` property set to `MessageUpdate`. + +## Delete a message + +{`suspend messages.delete(serial: String, operationDescription: String? = null, operationMetadata: Map? = null): Message`} + +Delete a message in the chat room. This method performs a "soft delete" on a message, marking it as deleted rather than permanently removing it. The deleted message will still be visible in message history but will be flagged as deleted. Subscribers will receive a deletion event in real-time. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val deletedMessage = room.messages.delete( + serial = message.serial, + operationDescription = "Removed inappropriate content" +) + +println("Message deleted: ${deletedMessage.action}") +``` + + +An extension function overload is also available that accepts a `Message` object directly: + +{`suspend Messages.delete(message: Message, operationDescription: String? = null, operationMetadata: Map? = null): Message`} + + +```kotlin +val deletedMessage = room.messages.delete( + message = message, + operationDescription = "Removed inappropriate content" +) +``` + + +### Parameters + +The `delete()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| serial | Required | The unique identifier of the message to delete. | String | +| operationDescription | Optional | A human-readable description of why the message was deleted. | String | +| operationMetadata | Optional | Additional metadata about the operation. Do not use for authoritative information. | `Map` | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +This is a suspend function. It returns the deleted [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. The returned message will have its `action` property set to `MessageDelete`. + +## Collect messages as a Flow + +{`Messages.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits chat message events. This is an extension function on the `Messages` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.messages.asFlow().collect { event -> + println("${event.message.clientId}: ${event.message.text}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `ChatMessageEvent` events. The flow automatically manages the underlying subscription. + +## PaginatedResult + +A `PaginatedResult` represents a page of results from a paginated query such as [history()](#history) or [historyBeforeSubscribe()](#historyBeforeSubscribe). + +### Properties + + + +| Property | Description | Type | +| --- | --- | --- | +| items | The current page of results. | [`List`](/docs/chat/api/kotlin/message) | + +
+ +### Check for more pages + +hasNext(): Boolean + +Returns `true` if there are more pages available by calling `next()`. + +### Get next page + +{`suspend next(): PaginatedResult`} + +This is a suspend function. It returns the next page of results, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Example + + +```kotlin +import com.ably.chat.ChatMessageEventType +import com.ably.chat.OrderBy +import com.ably.chat.asFlow +import kotlinx.coroutines.launch + +val room = chatClient.rooms.get("my-room") +room.attach() + +// Subscribe to messages +val (unsubscribe, subscription) = room.messages.subscribe { event -> + val msg = event.message + + when (event.type) { + ChatMessageEventType.Created -> + println("${msg.clientId}: ${msg.text}") + ChatMessageEventType.Updated -> + println("Message updated: ${msg.text}") + ChatMessageEventType.Deleted -> + println("Message deleted: ${msg.serial}") + } +} + +// Or use Flow for reactive collection +launch { + room.messages.asFlow().collect { event -> + println("Message event: ${event.type}") + } +} + +// Get recent history +val history = room.messages.history(limit = 10) +history.items.forEach { msg -> + println("[History] ${msg.clientId}: ${msg.text}") +} + +// Send a message +val sent = room.messages.send(text = "Hello everyone!") + +// Update the message +room.messages.update( + serial = sent.serial, + text = "Hello everyone! (edited)" +) + +// Clean up +unsubscribe() +``` + From de14703c45821ee1e3869f9cf3b119e4a82a7121 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:02 +0000 Subject: [PATCH 06/13] Review and update Chat Kotlin Message API reference Separate with() overloads into distinct signature blocks with code examples, convert property tables to description-based nullability. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/message.mdx | 235 +++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/message.mdx diff --git a/src/pages/docs/chat/api/kotlin/message.mdx b/src/pages/docs/chat/api/kotlin/message.mdx new file mode 100644 index 0000000000..8761b7f824 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/message.mdx @@ -0,0 +1,235 @@ +--- +title: Message +meta_description: "API reference for the Message interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Message API, with, copy, serial, clientId, text, timestamp, metadata, headers" +--- + +The `Message` interface represents a single message in a chat room. Messages are received through the [`messages.subscribe()`](/docs/chat/api/kotlin/messages#subscribe) method or retrieved via [`messages.history()`](/docs/chat/api/kotlin/messages#history). + +## Properties + +The `Message` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| serial | The unique identifier of the message. | String | +| clientId | The client ID of the user who created the message. | String | +| text | The text content of the message. | String | +| timestamp | The timestamp at which the message was created, in milliseconds since epoch. | Long | +| metadata | Extra information attached to the message for features like animations or linking to external resources. Always set; empty object if no metadata was provided. |
| +| headers | Additional information in Ably realtime message extras, usable for features like livestream timestamping or message flagging. Always set; empty map if none provided. | `Map` | +| action | The action type indicating if the message was created, updated, or deleted. |
| +| version | Information about the current version of this message. |
| +| reactions | The reactions summary for this message. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| | Key-value pairs that can be attached to a message for features like animations, styling hints, or links to external resources. Keys must be non-empty strings. Values can be any JSON-serializable type. Always present on a message, defaults to an empty object if not provided. | `JsonObject` | + + + + + +| Value | Description | +| --- | --- | +| MessageCreate | The message was newly created. The value is `message.create`. | +| MessageUpdate | The message was updated. The value is `message.update`. | +| MessageDelete | The message was deleted. The value is `message.delete`. | + + + + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| serial | Required | The unique identifier for this version. | String | +| timestamp | Required | When this version was created, in milliseconds since epoch. | Long | +| clientId | Optional | The client ID of the user who performed an update or deletion. | String | +| description | Optional | A description of why this version was created. | String | +| metadata | Optional | Additional metadata about the operation. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| | Metadata supplied to a message update or deletion request, or `null`. Do not use metadata for authoritative information. There is no server-side validation. When reading the metadata, treat it like user input. | `Map` | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| unique | Reactions counted with the "unique" strategy (one per client per message). Maps reaction name to summary. | `Map`>` | +| distinct | Reactions counted with the "distinct" strategy (one of each type per client). Maps reaction name to summary. | `Map`>` | +| multiple | Reactions counted with the "multiple" strategy (unlimited per client). Maps reaction name to summary. | `Map`>` | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| total | The total number of clients who have reacted with this name. | Int | +| clientIds | A list of the client IDs of all clients who have reacted with this name. | `List` | +| clipped | Whether the client IDs list has been truncated. | Boolean | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| total | The total count of reactions with this name across all clients. | Int | +| clientIds | A map of client ID to the count each client has contributed. | `Map` | +| totalClientIds | The total number of distinct clients. | Int | +| totalUnidentified | The total count from unidentified clients not included in `clientIds`. | Int | +| clipped | Whether the client IDs map has been truncated. | Boolean | + + + +## Apply an event to a message + +{`Message.with(event: ChatMessageEvent): Message`} + +Creates a new message instance with a chat message event applied. This is useful for updating a local message state when receiving update or delete events. Returns the same instance if the event would be a no-op (for example, applying an older version). + +This is an extension function on the `Message` interface. + + +```kotlin +val updatedMessage = message.with(updateEvent) +``` + + +An overload is also available for reaction summary events: + +{`Message.with(event: MessageReactionSummaryEvent): Message`} + + +```kotlin +val updatedMessage = message.with(reactionSummaryEvent) +``` + + +### Parameters + +The `with()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| event | Required | The event to apply to the message. |
or
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of the message event. | | +| message | The message that was received. | [Message](/docs/chat/api/kotlin/message) | + +
+ + + +| Value | Description | +| --- | --- | +| Created | A new chat message was received. | +| Updated | A chat message was updated. | +| Deleted | A chat message was deleted. | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| type | The event type. | MessageReactionSummaryEventType | +| messageSerial | The serial of the message. | String | +| reactions | The aggregated reaction counts. | | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +Returns a new message instance with the event applied, or the same instance if the event would be a no-op. + +## Copy a message + +{`Message.copy(text: String = this.text, headers: Map = this.headers, metadata: JsonObject = this.metadata): Message`} + +Creates a copy of the message with specified fields replaced. This is an extension function on the `Message` interface. + + +```kotlin +val messageCopy = message.copy(text = "New text") +``` + + +### Parameters + +The `copy()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| text | Optional | The new text content. Defaults to the current text. | String | +| headers | Optional | The new headers. Defaults to the current headers. | `Map` | +| metadata | Optional | The new metadata. Defaults to the current metadata. | `JsonObject` | + +
+ +### Returns + +[`Message`](/docs/chat/api/kotlin/message) + +Returns a new message instance with the specified fields replaced. + +## Example + + +```kotlin +import com.ably.chat.MessageAction + +// Subscribe to messages and handle different actions +room.messages.subscribe { event -> + val message = event.message + + println("Serial: ${message.serial}") + println("From: ${message.clientId}") + println("Text: ${message.text}") + println("Sent at: ${message.timestamp}") + println("Action: ${message.action}") + + // Check message version for updates or deletions + if (message.action == MessageAction.MessageUpdate) { + println("Updated by: ${message.version.clientId}") + println("Update reason: ${message.version.description}") + } + + if (message.action == MessageAction.MessageDelete) { + println("Deleted by: ${message.version.clientId}") + println("Delete reason: ${message.version.description}") + } + + // Check reaction summary + for ((name, summary) in message.reactions.distinct) { + println("$name: ${summary.total} reactions from ${summary.clientIds.size} clients") + } +} +``` + From 902743871d3970e65752672d281562c94841c050 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:07 +0000 Subject: [PATCH 07/13] Review and update Chat Kotlin Presence API reference Remove nullable type syntax from parameter tables, convert PresenceMember to description-based nullability for interface properties. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/presence.mdx | 350 ++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/presence.mdx diff --git a/src/pages/docs/chat/api/kotlin/presence.mdx b/src/pages/docs/chat/api/kotlin/presence.mdx new file mode 100644 index 0000000000..0bf6564a3c --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/presence.mdx @@ -0,0 +1,350 @@ +--- +title: Presence +meta_description: "API reference for the Presence interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Presence API, enter, leave, update, get, isUserPresent, subscribe, asFlow, online users" +--- + +The `Presence` interface provides methods for tracking which users are currently in a chat room. Access it via `room.presence`. + + +```kotlin +val presence = room.presence +``` + + +## Enter presence + +{`suspend presence.enter(data: JsonObject? = null): Unit`} + +Enters the current user into the chat room presence set. This notifies other users that you have joined the room. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) before calling this method. + + +```kotlin +room.presence.enter(buildJsonObject { + put("status", JsonPrimitive("online")) + put("nickname", JsonPrimitive("Alice")) +}) +``` + + +### Parameters + +The `enter()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| data | Optional | JSON-serializable data to associate with the user's presence. | `JsonObject` | + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the user has successfully entered the presence set, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Update presence data + +{`suspend presence.update(data: JsonObject? = null): Unit`} + +Updates the presence data for the current user in the chat room. Use this to change your status or other presence information without leaving and re-entering. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) before calling this method. + + +```kotlin +room.presence.update(buildJsonObject { + put("status", JsonPrimitive("away")) + put("nickname", JsonPrimitive("Alice")) +}) +``` + + +### Parameters + +The `update()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| data | Optional | JSON-serializable data to replace the user's current presence data. | `JsonObject` | + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the presence data has been updated, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Leave presence + +{`suspend presence.leave(data: JsonObject? = null): Unit`} + +Removes the current user from the chat room presence set. This notifies other users that you have left the room. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) before calling this method. + + +```kotlin +room.presence.leave(buildJsonObject { + put("status", JsonPrimitive("offline")) +}) +``` + + +### Parameters + +The `leave()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| data | Optional | Final presence data to include with the leave event. | `JsonObject` | + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the user has left the presence set, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Get current presence members + +{`suspend presence.get(waitForSync: Boolean = true, clientId: String? = null, connectionId: String? = null): List`} + +Retrieves the current members present in the chat room. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) before calling this method. + + +```kotlin +val members = room.presence.get() + +members.forEach { member -> + println("${member.clientId} is present") +} +``` + + +### Parameters + +The `get()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| waitForSync | Optional | Whether to wait for a full presence set synchronization before returning results. Default `true`. | Boolean | +| clientId | Optional | Filters the returned presence members by a specific client ID. | String | +| connectionId | Optional | Filters the returned presence members by a specific connection ID. | String | + +
+ +### Returns + +`List` + +This is a suspend function. It returns a list of presence members currently in the room, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + + + +| Property | Description | Type | +| --- | --- | --- | +| clientId | The client ID of the present user. | String | +| connectionId | The connection ID of the present user. | String | +| data | The presence data associated with the user, or `null`. | `JsonObject` | +| extras | Additional data included with the presence message. | `JsonObject` | +| updatedAt | When this presence state was last updated, in milliseconds since epoch. | Long | + +
+ +## Check if a user is present + +{`suspend presence.isUserPresent(clientId: String): Boolean`} + +Checks whether a specific user is currently present in the chat room. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) before calling this method. + + +```kotlin +val isAliceHere = room.presence.isUserPresent("alice-123") +println("Alice is present: $isAliceHere") +``` + + +### Parameters + +The `isUserPresent()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| clientId | Required | The client ID of the user to check. | String | + +
+ +### Returns + +`Boolean` + +This is a suspend function. It returns `true` if the user is present or `false` otherwise, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscribe to presence events + +{`presence.subscribe(listener: PresenceListener): Subscription`} + +Subscribes to all presence events in the chat room. Receive notifications when users enter, leave, or update their presence data. + + +```kotlin +import com.ably.chat.PresenceEventType + +val subscription = room.presence.subscribe { event -> + val member = event.member + when (event.type) { + PresenceEventType.Enter -> + println("${member.clientId} joined") + PresenceEventType.Leave -> + println("${member.clientId} left") + PresenceEventType.Update -> + println("${member.clientId} updated their status") + PresenceEventType.Present -> + println("${member.clientId} is present") + } +} + +// To stop receiving presence events +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback function invoked when any presence event occurs. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of presence event. | | +| member | The presence member associated with this event. |
| + +
+ + + +| Value | Description | +| --- | --- | +| Enter | A user has entered the presence set. | +| Leave | A user has left the presence set. | +| Update | A user has updated their presence data. | +| Present | Indicates a user is present (received during initial sync). | + + + +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from presence events + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving presence events. + +## Collect presence events as a Flow + +{`Presence.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits presence events. This is an extension function on the `Presence` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.presence.asFlow().collect { event -> + println("${event.type}: ${event.member.clientId}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `PresenceEvent` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.PresenceEventType +import com.ably.chat.asFlow +import kotlinx.coroutines.launch +import kotlinx.serialization.json.JsonPrimitive +import kotlinx.serialization.json.buildJsonObject + +val room = chatClient.rooms.get("my-room") +room.attach() + +// Subscribe to presence events with a listener +val subscription = room.presence.subscribe { event -> + val member = event.member + println("${event.type}: ${member.clientId}") + member.data?.let { data -> + println("Data: $data") + } +} + +// Or use Flow for reactive collection +launch { + room.presence.asFlow().collect { event -> + println("Presence: ${event.type} - ${event.member.clientId}") + } +} + +// Enter the room with custom data +room.presence.enter(buildJsonObject { + put("status", JsonPrimitive("online")) + put("nickname", JsonPrimitive("Alice")) +}) + +// Get everyone currently in the room +val members = room.presence.get() +println("${members.size} users in room") + +// Update your status +room.presence.update(buildJsonObject { + put("status", JsonPrimitive("away")) +}) + +// Check if a specific user is present +val isBobHere = room.presence.isUserPresent("bob-456") + +// Leave when done +room.presence.leave() +subscription.unsubscribe() +``` + From 6380085697091ebeb31bb463d02284e1b2fbc304 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:11 +0000 Subject: [PATCH 08/13] Add Chat Kotlin Typing API reference Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/typing.mdx | 214 ++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/typing.mdx diff --git a/src/pages/docs/chat/api/kotlin/typing.mdx b/src/pages/docs/chat/api/kotlin/typing.mdx new file mode 100644 index 0000000000..b2e7998427 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/typing.mdx @@ -0,0 +1,214 @@ +--- +title: Typing +meta_description: "API reference for the Typing interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Typing API, keystroke, stop, subscribe, asFlow, typing indicators" +--- + +The `Typing` interface provides methods for sending and receiving typing indicators in a chat room. Access it via `room.typing`. + + +```kotlin +val typing = room.typing +``` + + +## Properties + +The `Typing` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| current | The current set of client IDs who are typing in the room. | `Set` | + +
+ +## Start typing + +{`suspend typing.keystroke(): Unit`} + +Sends a typing started event to notify other users that the current user is typing. + +Events are throttled according to the [`heartbeatThrottle`](/docs/chat/api/kotlin/rooms#get) room option to prevent excessive network traffic. If called within the throttle interval, the operation becomes a no-op. Multiple rapid calls are serialized to maintain consistency. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) and the connection must be in the [`Connected`](/docs/chat/api/kotlin/connection) state. + + +```kotlin +// Call this when the user starts typing +room.typing.keystroke() +``` + + +### Returns + +`Unit` + +This is a suspend function. It completes when the typing event has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Stop typing + +{`suspend typing.stop(): Unit`} + +Sends a typing stopped event to notify other users that the current user has stopped typing. + +If the user is not currently typing, this operation is a no-op. Multiple rapid calls are serialized to maintain consistency. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) and the connection must be in the [`Connected`](/docs/chat/api/kotlin/connection) state. + + +```kotlin +// Call this when the user stops typing or clears the input +room.typing.stop() +``` + + +### Returns + +`Unit` + +This is a suspend function. It completes when the stop event has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscribe to typing events + +{`typing.subscribe(listener: TypingListener): Subscription`} + +Subscribes to typing events from users in the chat room. Receives updates whenever a user starts or stops typing, providing real-time feedback about who is currently composing messages. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) to receive typing events. + + +```kotlin +val subscription = room.typing.subscribe { event -> + println("Currently typing: ${event.currentlyTyping}") +} + +// To stop receiving typing events +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback invoked when the typing state changes. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of the event. | TypingSetEventType | +| currentlyTyping | Set of client IDs currently typing in the room. | `Set` | +| change | Information about the specific change that triggered this event. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| clientId | The client ID whose typing state changed. | String | +| type | Whether the user started or stopped typing. | | + +
+ + + +| Value | Description | +| --- | --- | +| Started | A user has started typing. | +| Stopped | A user has stopped typing. | + + + +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from typing events + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving typing events. + +## Collect typing events as a Flow + +{`Typing.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits typing events. This is an extension function on the `Typing` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.typing.asFlow().collect { event -> + println("Currently typing: ${event.currentlyTyping}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `TypingSetEvent` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.asFlow +import kotlinx.coroutines.launch +import kotlin.time.Duration.Companion.seconds + +val room = chatClient.rooms.get("my-room") { + typing { + heartbeatThrottle = 5.seconds // Throttle typing events to every 5 seconds + } +} + +room.attach() + +// Subscribe to typing events with a listener +val subscription = room.typing.subscribe { event -> + val typingUsers = event.currentlyTyping + + when { + typingUsers.isEmpty() -> println("No one is typing") + typingUsers.size == 1 -> println("${typingUsers.first()} is typing...") + else -> println("${typingUsers.joinToString(", ")} are typing...") + } +} + +// Or use Flow for reactive collection +launch { + room.typing.asFlow().collect { event -> + println("Typing users: ${event.currentlyTyping}") + } +} + +// Notify that the current user is typing +room.typing.keystroke() + +// Notify that the current user has stopped typing +room.typing.stop() + +// Check who is currently typing +println("Currently typing: ${room.typing.current}") + +// Clean up +subscription.unsubscribe() +``` + From d156955f119ca094fa28bc2b31bacb88d2c59bcb Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:15 +0000 Subject: [PATCH 09/13] Add Chat Kotlin Occupancy API reference Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/occupancy.mdx | 176 +++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/occupancy.mdx diff --git a/src/pages/docs/chat/api/kotlin/occupancy.mdx b/src/pages/docs/chat/api/kotlin/occupancy.mdx new file mode 100644 index 0000000000..93c6cb1491 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/occupancy.mdx @@ -0,0 +1,176 @@ +--- +title: Occupancy +meta_description: "API reference for the Occupancy interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Occupancy API, get, subscribe, asFlow, connections, presence members, user count" +--- + +The `Occupancy` interface provides methods for tracking the number of users in a chat room. Access it via `room.occupancy`. + + +```kotlin +val occupancy = room.occupancy +``` + + +## Properties + +The `Occupancy` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| current | The latest occupancy data cached from realtime events. Returns `null` if no occupancy events have been received yet since room attachment. Requires `enableEvents` to be `true` in the [room's occupancy options](/docs/chat/api/kotlin/rooms#get). |
or null | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| connections | The number of active connections to the room. | Int | +| presenceMembers | The number of users in the presence set. | Int | + + + +## Get current occupancy + +{`suspend occupancy.get(): OccupancyData`} + +Fetches the current occupancy of the chat room from the server. Retrieves the latest occupancy metrics, including the number of active connections and presence members. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +val data = room.occupancy.get() +println("Connections: ${data.connections}") +println("Presence members: ${data.presenceMembers}") +``` + + +### Returns + +`OccupancyData` + +This is a suspend function. It returns the current occupancy data, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscribe to occupancy events + +{`occupancy.subscribe(listener: OccupancyListener): Subscription`} + +Subscribes to occupancy updates for the chat room. Receives updates whenever the number of connections or present members in the room changes. + +Requires `enableEvents` to be `true` in the [room's occupancy options](/docs/chat/api/kotlin/rooms#get). The room should be [attached](/docs/chat/api/kotlin/room#attach) to receive occupancy events. + + +```kotlin +val subscription = room.occupancy.subscribe { event -> + println("Connections: ${event.occupancy.connections}") + println("Presence members: ${event.occupancy.presenceMembers}") +} + +// To stop receiving occupancy updates +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback invoked when room occupancy changes. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of occupancy event. | OccupancyEventType | +| occupancy | The current occupancy data. | | + +
+ +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from occupancy events + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving occupancy events. + +## Collect occupancy events as a Flow + +{`Occupancy.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits occupancy events. This is an extension function on the `Occupancy` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.occupancy.asFlow().collect { event -> + println("Connections: ${event.occupancy.connections}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `OccupancyEvent` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.asFlow +import kotlinx.coroutines.launch + +val room = chatClient.rooms.get("my-room") { + occupancy { + enableEvents = true // Required for subscribe() and current property + } +} + +room.attach() + +// Subscribe to occupancy changes with a listener +val subscription = room.occupancy.subscribe { event -> + val (connections, presenceMembers) = event.occupancy + println("Room has $connections connections and $presenceMembers presence members") +} + +// Or use Flow for reactive collection +launch { + room.occupancy.asFlow().collect { event -> + println("Occupancy updated: ${event.occupancy.connections} connections") + } +} + +// Fetch occupancy on-demand (works even without enableEvents) +val occupancy = room.occupancy.get() +println("Initial occupancy: ${occupancy.connections} connections") + +// Access cached occupancy (requires enableEvents) +val cached = room.occupancy.current +cached?.let { + println("Cached occupancy: ${it.connections}") +} + +// Clean up +subscription.unsubscribe() +``` + From 4363dc8d489749a5a8f570f614efc5168255c673 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:19 +0000 Subject: [PATCH 10/13] Review and update Chat Kotlin RoomReactions API reference Remove nullable type syntax from parameter tables. Co-Authored-By: Claude Opus 4.6 --- .../docs/chat/api/kotlin/room-reactions.mdx | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/room-reactions.mdx diff --git a/src/pages/docs/chat/api/kotlin/room-reactions.mdx b/src/pages/docs/chat/api/kotlin/room-reactions.mdx new file mode 100644 index 0000000000..a937bf43f1 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/room-reactions.mdx @@ -0,0 +1,182 @@ +--- +title: RoomReactions +meta_description: "API reference for the RoomReactions interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, RoomReactions API, send, subscribe, asFlow, room reactions, ephemeral reactions" +--- + +The `RoomReactions` interface provides methods for sending and receiving ephemeral room-level reactions. These are commonly used for live interactions like floating emojis, applause, or other real-time feedback in chat rooms. Access it via `room.reactions`. + + +```kotlin +val reactions = room.reactions +``` + + +Unlike message reactions, room reactions are not persisted and are only visible to users currently connected to the room. + +## Send a room reaction + +{`suspend reactions.send(name: String, metadata: JsonObject? = null, headers: Map? = null): Unit`} + +Sends a room-level reaction. Room reactions are ephemeral events that are not associated with specific messages. + +The room should be [attached](/docs/chat/api/kotlin/room#attach) to send room reactions. The connection must be in the [`Connected`](/docs/chat/api/kotlin/connection) state. + + +```kotlin +room.reactions.send(name = "👍") +``` + + +### Parameters + +The `send()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| name | Required | The name of the reaction, typically an emoji or identifier. | String | +| metadata | Optional | Additional metadata to include with the reaction. | `JsonObject` | +| headers | Optional | Additional information in Ably message extras, usable for features like referencing external resources. | `Map` | + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the reaction has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscribe to room reactions + +{`reactions.subscribe(listener: RoomReactionListener): Subscription`} + +Subscribes to room-level reaction events. Receives all room reactions sent by any user in the room. This is useful for displaying floating reactions, triggering animations, or showing live audience engagement. + +The room should be [attached](/docs/chat/api/kotlin/room#attach) to receive reaction events. + + +```kotlin +val subscription = room.reactions.subscribe { event -> + println("${event.reaction.clientId} reacted with ${event.reaction.name}") +} + +// To stop receiving reactions +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback invoked when a room reaction is received. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The type of the event. | RoomReactionEventType | +| reaction | The reaction that was received. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| name | The name of the reaction (for example, an emoji). | String | +| clientId | The client ID of the user who sent the reaction. | String | +| metadata | Additional metadata included with the reaction. Empty object if none provided. | `JsonObject` | +| headers | Additional information from Ably message extras. Empty map if none provided. | `Map` | +| createdAt | When the reaction was sent, in milliseconds since epoch. | Long | +| isSelf | Whether the reaction was sent by the current client. | Boolean | + + + +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from room reactions + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving room reaction events. + +## Collect room reactions as a Flow + +{`RoomReactions.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits room reaction events. This is an extension function on the `RoomReactions` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.reactions.asFlow().collect { event -> + println("${event.reaction.clientId} reacted with ${event.reaction.name}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `RoomReactionEvent` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.asFlow +import kotlinx.coroutines.launch + +val room = chatClient.rooms.get("my-room") +room.attach() + +// Subscribe to room reactions with a listener +val subscription = room.reactions.subscribe { event -> + println("${event.reaction.clientId} sent ${event.reaction.name}") + + // Check if it's your own reaction + if (event.reaction.isSelf) { + println("This was my reaction") + } +} + +// Or use Flow for reactive collection +launch { + room.reactions.asFlow().collect { event -> + println("Reaction: ${event.reaction.name}") + } +} + +// Send a simple reaction +room.reactions.send(name = "🎉") + +// Send a reaction with metadata +room.reactions.send( + name = "🎉", + metadata = buildJsonObject { + put("animation", JsonPrimitive("confetti")) + put("color", JsonPrimitive("gold")) + } +) + +// Clean up +subscription.unsubscribe() +``` + From 021598bf7d398ecefa1af285bff1b436ba1067b7 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:14:23 +0000 Subject: [PATCH 11/13] Review and update Chat Kotlin Connection API reference Convert property tables to description-based nullability for interface properties. Co-Authored-By: Claude Opus 4.6 --- src/pages/docs/chat/api/kotlin/connection.mdx | 168 ++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/connection.mdx diff --git a/src/pages/docs/chat/api/kotlin/connection.mdx b/src/pages/docs/chat/api/kotlin/connection.mdx new file mode 100644 index 0000000000..ef10ef701b --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/connection.mdx @@ -0,0 +1,168 @@ +--- +title: Connection +meta_description: "API reference for the Connection interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, Connection API, onStatusChange, statusAsFlow, status, error, ConnectionStatus" +--- + +The `Connection` interface represents the connection to Ably and provides methods to monitor connection status changes. Access the connection via `chatClient.connection`. + + +```kotlin +val connection = chatClient.connection +``` + + +## Properties + +The `Connection` interface has the following properties: + + + +| Property | Description | Type | +| --- | --- | --- | +| status | The current connection status. |
| +| error | The error that caused the connection to enter its current status, if any, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | + +
+ + + +| Status | Description | +| --- | --- | +| Initialized | A temporary state for when the library is first initialized. | +| Connecting | The library is currently connecting to Ably. | +| Connected | A connection exists and is active. | +| Disconnected | The library is currently disconnected from Ably, but will attempt to reconnect. | +| Suspended | The library is in an extended state of disconnection, but will attempt to reconnect. | +| Failed | The library is currently disconnected from Ably and will not attempt to reconnect. | +| Closing | An explicit request by the developer to close the connection has been sent to the Ably service. | +| Closed | The connection has been explicitly closed by the client. No reconnection attempts are made automatically. | + + + +## Subscribe to connection status changes + +{`connection.onStatusChange(listener: ConnectionStatusListener): Subscription`} + +Registers a listener to be notified of connection status changes. + + +```kotlin +val subscription = chatClient.connection.onStatusChange { change -> + println("Status changed from ${change.previous} to ${change.current}") + change.error?.let { error -> + println("Error: $error") + } + change.retryIn?.let { retryIn -> + println("Retrying in $retryIn ms") + } +} + +// To unsubscribe +subscription.unsubscribe() +``` + + +### Parameters + +The `onStatusChange()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | A callback invoked on status changes. |
| + +
+ + + +| Parameter | Description | Type | +| --- | --- | --- | +| change | The status change event. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| current | The new connection status. | | +| previous | The previous connection status. |
| +| error | An error that provides a reason why the connection has entered the new status, if applicable, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | +| retryIn | The time in milliseconds that the client will wait before attempting to reconnect, if applicable, or `null`. | Long | + +
+ +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Deregister the listener + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to deregister the connection status listener. + +## Collect connection status changes as a Flow + +{`Connection.statusAsFlow(): Flow`} + +Returns a Kotlin `Flow` that emits connection status changes. This is an extension function on the `Connection` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + chatClient.connection.statusAsFlow().collect { change -> + println("Status changed from ${change.previous} to ${change.current}") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `ConnectionStatusChange` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.ConnectionStatus +import kotlinx.coroutines.launch + +// Monitor connection status with a listener +val subscription = chatClient.connection.onStatusChange { change -> + when (change.current) { + ConnectionStatus.Connected -> + println("Connected to Ably") + ConnectionStatus.Disconnected -> + println("Disconnected, will retry...") + ConnectionStatus.Suspended -> + println("Connection suspended, retrying in ${change.retryIn} ms") + ConnectionStatus.Failed -> + println("Connection failed: ${change.error}") + else -> {} + } +} + +// Or use Flow for reactive collection +launch { + chatClient.connection.statusAsFlow().collect { change -> + println("Status: ${change.current}") + } +} + +// Check current status +println("Current status: ${chatClient.connection.status}") + +// Clean up +subscription.unsubscribe() +``` + From d1d8bbacd1ebbcdf39da34626f752bb15453fff2 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:16:07 +0000 Subject: [PATCH 12/13] Review and update Chat Kotlin MessageReactions API reference Co-Authored-By: Claude Opus 4.6 --- .../chat/api/kotlin/message-reactions.mdx | 425 ++++++++++++++++++ 1 file changed, 425 insertions(+) create mode 100644 src/pages/docs/chat/api/kotlin/message-reactions.mdx diff --git a/src/pages/docs/chat/api/kotlin/message-reactions.mdx b/src/pages/docs/chat/api/kotlin/message-reactions.mdx new file mode 100644 index 0000000000..f5fd69c2f8 --- /dev/null +++ b/src/pages/docs/chat/api/kotlin/message-reactions.mdx @@ -0,0 +1,425 @@ +--- +title: MessageReactions +meta_description: "API reference for the MessageReactions interface in the Ably Chat Kotlin SDK." +meta_keywords: "Ably Chat SDK, Kotlin, MessageReactions API, send, delete, subscribe, subscribeRaw, clientReactions, asFlow, message reactions" +--- + +The `MessageReactions` interface provides methods to send, delete, and subscribe to reactions on specific messages. Unlike room reactions, message reactions are persisted and associated with individual chat messages. Access it via `room.messages.reactions`. + + +```kotlin +val reactions = room.messages.reactions +``` + + +Message reactions support three counting strategies: +- **Unique**: One reaction per client per message (like iMessage, WhatsApp) +- **Distinct**: One reaction of each type per client (like Slack) +- **Multiple**: Unlimited reactions including repeats (like Medium claps) + +## Send a reaction to a message + +{`suspend reactions.send(messageSerial: String, name: String, type: MessageReactionType? = null, count: Int? = null): Unit`} + +Sends a reaction to a specific chat message. The reaction is persisted and contributes to the message's reaction summary. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +room.messages.reactions.send( + messageSerial = "message-serial-123", + name = "👍" +) +``` + + +An extension function overload is also available that accepts a `Message` object directly: + +{`suspend MessageReactions.send(message: Message, name: String, type: MessageReactionType? = null, count: Int = 1): Unit`} + + +```kotlin +room.messages.reactions.send( + message = message, + name = "👍" +) +``` + + +### Parameters + +The `send()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| messageSerial | Required | The serial of the message to react to. | String | +| name | Required | The reaction identifier, typically an emoji. | String | +| type | Optional | The counting strategy for this reaction. Defaults vary by room configuration. |
| +| count | Optional | Number of times to count this reaction. Only applies to `Multiple` type. | Int | + +
+ + + +| Value | Description | +| --- | --- | +| Unique | One reaction per client per message. A second reaction replaces the first. Similar to iMessage, Facebook Messenger, or WhatsApp. | +| Distinct | One reaction of each type per client per message. Multiple different reactions allowed. Similar to Slack. | +| Multiple | Unlimited reactions including repeats. Includes a count for batch reactions. Similar to Medium claps. | + + + +### Returns + +`Unit` + +This is a suspend function. It completes when the reaction has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Delete a reaction from a message + +{`suspend reactions.delete(messageSerial: String, name: String? = null, type: MessageReactionType? = null): Unit`} + +Removes a previously sent reaction from a chat message. + +This method uses the Ably Chat REST API and does not require the room to be attached. + + +```kotlin +room.messages.reactions.delete( + messageSerial = "message-serial-123", + name = "👍" +) +``` + + +An extension function overload is also available that accepts a `Message` object directly: + +{`suspend MessageReactions.delete(message: Message, name: String? = null, type: MessageReactionType? = null): Unit`} + + +```kotlin +room.messages.reactions.delete(message = message) +``` + + +### Parameters + +The `delete()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| messageSerial | Required | The serial of the message to remove the reaction from. | String | +| name | Optional | The reaction identifier to delete. Required except for `Unique` type. | String | +| type | Optional | The counting strategy of the reaction to delete. |
| + +
+ +### Returns + +`Unit` + +This is a suspend function. It completes when the reaction has been deleted, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Subscribe to reaction summaries + +{`reactions.subscribe(listener: MessageReactionListener): Subscription`} + +Subscribes to aggregated reaction count summaries for messages. Receives updates when the total reaction counts change on any message in the room. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) to receive reaction summary events. + + +```kotlin +val subscription = room.messages.reactions.subscribe { event -> + println("Message: ${event.messageSerial}") + println("Reactions: ${event.reactions}") +} + +// To stop receiving reaction summaries +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribe()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback invoked when reaction summaries change. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The event type. | MessageReactionSummaryEventType | +| messageSerial | The serial of the message. | String | +| reactions | The aggregated reaction counts. | | + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| unique | Reactions counted with the "unique" strategy (one per client per message). Maps reaction name to summary. | `Map`>` | +| distinct | Reactions counted with the "distinct" strategy (one of each type per client). Maps reaction name to summary. | `Map`>` | +| multiple | Reactions counted with the "multiple" strategy (unlimited per client). Maps reaction name to summary. | `Map`>` | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| total | The total number of clients who have reacted with this name. | Int | +| clientIds | A list of the client IDs of all clients who have reacted with this name. | `List` | +| clipped | Whether the client IDs list has been truncated. | Boolean | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| total | The total count of reactions with this name across all clients. | Int | +| clientIds | A map of client ID to the count each client has contributed. | `Map` | +| totalClientIds | The total number of distinct clients. | Int | +| totalUnidentified | The total count from unidentified clients not included in `clientIds`. | Int | +| clipped | Whether the client IDs map has been truncated. | Boolean | + + + +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from reaction summaries + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving reaction summary events. + +## Subscribe to individual reaction events + +{`reactions.subscribeRaw(listener: MessageRawReactionListener): Subscription`} + +Subscribes to individual reaction events, receiving notifications each time a user adds or removes a reaction. This provides more granular updates than the summary subscription. + +The room must be [attached](/docs/chat/api/kotlin/room#attach) to receive raw reaction events. Raw message reactions must also be enabled when [creating the room](/docs/chat/api/kotlin/rooms#get) by setting `rawMessageReactions = true` in the messages options. + + + + +```kotlin +val subscription = room.messages.reactions.subscribeRaw { event -> + when (event.type) { + MessageReactionEventType.Create -> + println("${event.reaction.clientId} reacted with ${event.reaction.name}") + MessageReactionEventType.Delete -> + println("${event.reaction.clientId} removed ${event.reaction.name}") + } +} + +// To stop receiving raw events +subscription.unsubscribe() +``` + + +### Parameters + +The `subscribeRaw()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| listener | Required | Callback invoked for each individual reaction event. |
| + +
+ + + +| Property | Description | Type | +| --- | --- | --- | +| type | The event type. | | +| timestamp | When the event occurred, in milliseconds since epoch. | Long | +| reaction | The reaction details. |
| + +
+ + + +| Value | Description | +| --- | --- | +| Create | A reaction was added. | +| Delete | A reaction was removed. | + + + + + +| Property | Description | Type | +| --- | --- | --- | +| messageSerial | The serial of the message. | String | +| type | The counting strategy. | | +| name | The reaction identifier. | String | +| count | The count for Multiple type reactions, or `null`. | Int | +| clientId | The client ID who sent the reaction. | String | + +
+ +### Returns + +[`Subscription`](/docs/chat/api/kotlin/rooms#Subscription) + +Returns a `Subscription` object. + +#### Unsubscribe from raw reaction events + +subscription.unsubscribe(): Unit + +Call `unsubscribe()` to stop receiving raw reaction events. + +## Get reactions for a specific client + +{`suspend reactions.clientReactions(messageSerial: String, clientId: String? = null): MessageReactionSummary`} + +Retrieves the reaction data for a specific client on a message. If no client ID is provided, returns reactions for the current user. + + +```kotlin +// Get current user's reactions on a message +val myReactions = room.messages.reactions.clientReactions("message-serial-123") + +// Get another user's reactions +val theirReactions = room.messages.reactions.clientReactions("message-serial-123", "user-456") +``` + + +### Parameters + +The `clientReactions()` method takes the following parameters: + + + +| Parameter | Required | Description | Type | +| --- | --- | --- | --- | +| messageSerial | Required | The serial of the message to get reactions for. | String | +| clientId | Optional | The client ID to get reactions for. Defaults to the current user. | String | + +
+ +### Returns + +`MessageReactionSummary` + +This is a suspend function. It returns the reaction data for the specified client, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. + +## Collect reaction summaries as a Flow + +{`MessageReactions.asFlow(): Flow`} + +Returns a Kotlin `Flow` that emits reaction summary events. This is an extension function on the `MessageReactions` interface that provides a reactive alternative to listener-based subscriptions. + + +```kotlin +import kotlinx.coroutines.launch + +launch { + room.messages.reactions.asFlow().collect { event -> + println("Message ${event.messageSerial} reactions updated") + } +} +``` + + +### Returns + +`Flow` + +Returns a `Flow` that emits `MessageReactionSummaryEvent` events. The flow automatically manages the underlying subscription. + +## Example + + +```kotlin +import com.ably.chat.MessageReactionType +import com.ably.chat.MessageReactionEventType +import com.ably.chat.asFlow +import kotlinx.coroutines.launch + +val room = chatClient.rooms.get("my-room") { + messages { + rawMessageReactions = true + } +} +room.attach() + +// Subscribe to reaction summaries +val summarySub = room.messages.reactions.subscribe { event -> + val (messageSerial, reactions) = event + + // Update UI with reaction counts + for ((name, summary) in reactions.distinct) { + println("$name: ${summary.total} reactions from ${summary.clientIds.size} clients") + } +} + +// Subscribe to individual reaction events for animations +val rawSub = room.messages.reactions.subscribeRaw { event -> + if (event.type == MessageReactionEventType.Create) { + println("${event.reaction.clientId} reacted with ${event.reaction.name}") + } +} + +// Or use Flow for reactive collection +launch { + room.messages.reactions.asFlow().collect { event -> + println("Reactions updated for ${event.messageSerial}") + } +} + +// Send a distinct reaction (Slack-style) +room.messages.reactions.send( + messageSerial = "message-serial-123", + name = "👍", + type = MessageReactionType.Distinct +) + +// Send multiple reactions (Medium-style claps) +room.messages.reactions.send( + messageSerial = "message-serial-456", + name = "👏", + type = MessageReactionType.Multiple, + count = 5 +) + +// Remove a reaction +room.messages.reactions.delete( + messageSerial = "message-serial-123", + name = "👍" +) + +// Check what reactions I've sent on a message +val myReactions = room.messages.reactions.clientReactions("message-serial-123") +println("My reactions: $myReactions") + +// Clean up +summarySub.unsubscribe() +rawSub.unsubscribe() +``` + From f75777b780e5a3bfed30856747032b8648e9a21e Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:03:19 +0000 Subject: [PATCH 13/13] Address review comments --- .../docs/chat/api/kotlin/chat-client.mdx | 12 ++++---- src/pages/docs/chat/api/kotlin/connection.mdx | 24 +++++++-------- .../chat/api/kotlin/message-reactions.mdx | 12 ++++---- src/pages/docs/chat/api/kotlin/message.mdx | 13 ++------ src/pages/docs/chat/api/kotlin/messages.mdx | 16 +++++----- src/pages/docs/chat/api/kotlin/occupancy.mdx | 6 ++-- src/pages/docs/chat/api/kotlin/presence.mdx | 14 ++++----- .../docs/chat/api/kotlin/room-reactions.mdx | 4 +-- src/pages/docs/chat/api/kotlin/room.mdx | 30 +++++++++---------- src/pages/docs/chat/api/kotlin/rooms.mdx | 6 ++-- src/pages/docs/chat/api/kotlin/typing.mdx | 6 ++-- 11 files changed, 68 insertions(+), 75 deletions(-) diff --git a/src/pages/docs/chat/api/kotlin/chat-client.mdx b/src/pages/docs/chat/api/kotlin/chat-client.mdx index 22d17f7228..747f3f04a9 100644 --- a/src/pages/docs/chat/api/kotlin/chat-client.mdx +++ b/src/pages/docs/chat/api/kotlin/chat-client.mdx @@ -39,7 +39,7 @@ The `ChatClient` interface has the following properties: | --- | --- | --- | | rooms | The rooms object, used to get or create chat room instances. | [Rooms](/docs/chat/api/kotlin/rooms) | | connection | The connection object, used to monitor the connection status with Ably. | [Connection](/docs/chat/api/kotlin/connection) | -| clientId | The client ID configured on the underlying Ably Realtime client. Used to identify the current user. May be `null` until authenticated with a token. | String | +| clientId | The client ID configured on the underlying Ably Realtime client. Used to identify the current user. | String? | | realtime | The underlying Ably Realtime client instance. Note: this property is experimental and may change in a future release. | RealtimeClient | | clientOptions | The resolved configuration options with defaults applied. | | @@ -125,8 +125,8 @@ A specialized exception class for errors that occur during chat operations. `Cha | Property | Description | Type | | --- | --- | --- | | errorInfo | Detailed error information including Ably-specific error codes and HTTP status codes. | [ErrorInfo](#errorinfo) | -| message | The exception message, or `null`. | String | -| cause | The underlying cause of the exception, if any, or `null`. | Throwable | +| message | The exception message. | String? | +| cause | The underlying cause of the exception, if any. | Throwable? |
@@ -155,9 +155,9 @@ A standardized, generic Ably error object that contains an Ably-specific status | code | Ably-specific error code. | Int | | statusCode | HTTP status code corresponding to this error, where applicable. | Int | | message | Additional information about the error. | String | -| href | A URL providing more information about the error, or `null`. | String | -| cause | The underlying cause of the error, or `null`. | ErrorInfo | -| requestId | The request ID if the error originated from an API request, or `null`. | String | +| href | A URL providing more information about the error. | String? | +| cause | The underlying cause of the error. | ErrorInfo? | +| requestId | The request ID if the error originated from an API request. | String? | diff --git a/src/pages/docs/chat/api/kotlin/connection.mdx b/src/pages/docs/chat/api/kotlin/connection.mdx index ef10ef701b..4c1dbc802a 100644 --- a/src/pages/docs/chat/api/kotlin/connection.mdx +++ b/src/pages/docs/chat/api/kotlin/connection.mdx @@ -21,7 +21,7 @@ The `Connection` interface has the following properties: | Property | Description | Type | | --- | --- | --- | | status | The current connection status. | | -| error | The error that caused the connection to enter its current status, if any, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | +| error | The error that caused the connection to enter its current status, if any. | [ErrorInfo?](/docs/chat/api/kotlin/chat-client#errorinfo) |
@@ -29,14 +29,14 @@ The `Connection` interface has the following properties: | Status | Description | | --- | --- | -| Initialized | A temporary state for when the library is first initialized. | -| Connecting | The library is currently connecting to Ably. | -| Connected | A connection exists and is active. | -| Disconnected | The library is currently disconnected from Ably, but will attempt to reconnect. | -| Suspended | The library is in an extended state of disconnection, but will attempt to reconnect. | -| Failed | The library is currently disconnected from Ably and will not attempt to reconnect. | -| Closing | An explicit request by the developer to close the connection has been sent to the Ably service. | -| Closed | The connection has been explicitly closed by the client. No reconnection attempts are made automatically. | +| Initialized | A temporary state for when the library is first initialized. The value is `initialized`. | +| Connecting | The library is currently connecting to Ably. The value is `connecting`. | +| Connected | A connection exists and is active. The value is `connected`. | +| Disconnected | The library is currently disconnected from Ably, but will attempt to reconnect. The value is `disconnected`. | +| Suspended | The library is in an extended state of disconnection, but will attempt to reconnect. The value is `suspended`. | +| Failed | The library is currently disconnected from Ably and will not attempt to reconnect. The value is `failed`. | +| Closing | An explicit request by the developer to close the connection has been sent to the Ably service. The value is `closing`. | +| Closed | The connection has been explicitly closed by the client. No reconnection attempts are made automatically. The value is `closed`. | @@ -89,8 +89,8 @@ The `onStatusChange()` method takes the following parameters: | --- | --- | --- | | current | The new connection status. | | | previous | The previous connection status. |
| -| error | An error that provides a reason why the connection has entered the new status, if applicable, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | -| retryIn | The time in milliseconds that the client will wait before attempting to reconnect, if applicable, or `null`. | Long | +| error | An error that provides a reason why the connection has entered the new status, if applicable. | [ErrorInfo?](/docs/chat/api/kotlin/chat-client#errorinfo) | +| retryIn | The time in milliseconds that the client will wait before attempting to reconnect, if applicable. | Long? |
@@ -102,7 +102,7 @@ Returns a `Subscription` object. #### Deregister the listener -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to deregister the connection status listener. diff --git a/src/pages/docs/chat/api/kotlin/message-reactions.mdx b/src/pages/docs/chat/api/kotlin/message-reactions.mdx index f5fd69c2f8..0bc2b360c7 100644 --- a/src/pages/docs/chat/api/kotlin/message-reactions.mdx +++ b/src/pages/docs/chat/api/kotlin/message-reactions.mdx @@ -76,7 +76,7 @@ The `send()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the reaction has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the reaction has been sent, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Delete a reaction from a message @@ -123,7 +123,7 @@ The `delete()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the reaction has been deleted, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the reaction has been deleted, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscribe to reaction summaries @@ -207,7 +207,7 @@ Returns a `Subscription` object. #### Unsubscribe from reaction summaries -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving reaction summary events. @@ -277,7 +277,7 @@ The `subscribeRaw()` method takes the following parameters: | messageSerial | The serial of the message. | String | | type | The counting strategy. | | | name | The reaction identifier. | String | -| count | The count for Multiple type reactions, or `null`. | Int | +| count | The count for Multiple type reactions. | Int? | | clientId | The client ID who sent the reaction. | String |
@@ -290,7 +290,7 @@ Returns a `Subscription` object. #### Unsubscribe from raw reaction events -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving raw reaction events. @@ -327,7 +327,7 @@ The `clientReactions()` method takes the following parameters: `MessageReactionSummary` -This is a suspend function. It returns the reaction data for the specified client, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns the reaction data for the specified client, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Collect reaction summaries as a Flow diff --git a/src/pages/docs/chat/api/kotlin/message.mdx b/src/pages/docs/chat/api/kotlin/message.mdx index 8761b7f824..7e6f81916d 100644 --- a/src/pages/docs/chat/api/kotlin/message.mdx +++ b/src/pages/docs/chat/api/kotlin/message.mdx @@ -50,19 +50,12 @@ The `Message` interface has the following properties: | --- | --- | --- | --- | | serial | Required | The unique identifier for this version. | String | | timestamp | Required | When this version was created, in milliseconds since epoch. | Long | -| clientId | Optional | The client ID of the user who performed an update or deletion. | String | -| description | Optional | A description of why this version was created. | String | -| metadata | Optional | Additional metadata about the operation. | | +| clientId | Optional | The client ID of the user who performed an update or deletion. | String? | +| description | Optional | A description of why this version was created. | String? | +| metadata | Optional | Additional metadata about the operation. | `Map?` |
- - -| Property | Description | Type | -| --- | --- | --- | -| | Metadata supplied to a message update or deletion request, or `null`. Do not use metadata for authoritative information. There is no server-side validation. When reading the metadata, treat it like user input. | `Map` | - - diff --git a/src/pages/docs/chat/api/kotlin/messages.mdx b/src/pages/docs/chat/api/kotlin/messages.mdx index f97ee8590a..0e59b9c49f 100644 --- a/src/pages/docs/chat/api/kotlin/messages.mdx +++ b/src/pages/docs/chat/api/kotlin/messages.mdx @@ -93,7 +93,7 @@ Returns a `MessagesSubscription` that extends [`Subscription`](/docs/chat/api/ko #### Unsubscribe from messages -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop listening for message events. @@ -121,7 +121,7 @@ The `historyBeforeSubscribe()` method takes the following parameters: [`PaginatedResult`](#PaginatedResult) -This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Send a message @@ -157,7 +157,7 @@ The `send()` method takes the following parameters: [`Message`](/docs/chat/api/kotlin/message) -This is a suspend function. It returns the sent [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns the sent [Message](/docs/chat/api/kotlin/message) object, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Get message history @@ -211,7 +211,7 @@ The `history()` method takes the following parameters: [`PaginatedResult`](#PaginatedResult) -This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns a [`PaginatedResult`](#PaginatedResult) containing a list of [Message](/docs/chat/api/kotlin/message) objects, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Get a specific message @@ -244,7 +244,7 @@ The `get()` method takes the following parameters: [`Message`](/docs/chat/api/kotlin/message) -This is a suspend function. It returns the [Message](/docs/chat/api/kotlin/message) object matching the given serial, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns the [Message](/docs/chat/api/kotlin/message) object matching the given serial, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Update a message @@ -300,7 +300,7 @@ The `update()` method takes the following parameters: [`Message`](/docs/chat/api/kotlin/message) -This is a suspend function. It returns the updated [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. The returned message will have its `action` property set to `MessageUpdate`. +This is a suspend function. It returns the updated [Message](/docs/chat/api/kotlin/message) object, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. The returned message will have its `action` property set to `MessageUpdate`. ## Delete a message @@ -352,7 +352,7 @@ The `delete()` method takes the following parameters: [`Message`](/docs/chat/api/kotlin/message) -This is a suspend function. It returns the deleted [Message](/docs/chat/api/kotlin/message) object, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. The returned message will have its `action` property set to `MessageDelete`. +This is a suspend function. It returns the deleted [Message](/docs/chat/api/kotlin/message) object, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. The returned message will have its `action` property set to `MessageDelete`. ## Collect messages as a Flow @@ -402,7 +402,7 @@ Returns `true` if there are more pages available by calling `next()`. {`suspend next(): PaginatedResult`} -This is a suspend function. It returns the next page of results, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns the next page of results, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Example diff --git a/src/pages/docs/chat/api/kotlin/occupancy.mdx b/src/pages/docs/chat/api/kotlin/occupancy.mdx index 93c6cb1491..48f8e455fa 100644 --- a/src/pages/docs/chat/api/kotlin/occupancy.mdx +++ b/src/pages/docs/chat/api/kotlin/occupancy.mdx @@ -20,7 +20,7 @@ The `Occupancy` interface has the following properties: | Property | Description | Type | | --- | --- | --- | -| current | The latest occupancy data cached from realtime events. Returns `null` if no occupancy events have been received yet since room attachment. Requires `enableEvents` to be `true` in the [room's occupancy options](/docs/chat/api/kotlin/rooms#get). | or null | +| current | The latest occupancy data cached from realtime events. Requires `enableEvents` to be `true` in the [room's occupancy options](/docs/chat/api/kotlin/rooms#get). |
? |
@@ -53,7 +53,7 @@ println("Presence members: ${data.presenceMembers}") `OccupancyData` -This is a suspend function. It returns the current occupancy data, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns the current occupancy data, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscribe to occupancy events @@ -104,7 +104,7 @@ Returns a `Subscription` object. #### Unsubscribe from occupancy events -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving occupancy events. diff --git a/src/pages/docs/chat/api/kotlin/presence.mdx b/src/pages/docs/chat/api/kotlin/presence.mdx index 0bf6564a3c..c0807170b3 100644 --- a/src/pages/docs/chat/api/kotlin/presence.mdx +++ b/src/pages/docs/chat/api/kotlin/presence.mdx @@ -45,7 +45,7 @@ The `enter()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the user has successfully entered the presence set, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the user has successfully entered the presence set, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Update presence data @@ -80,7 +80,7 @@ The `update()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the presence data has been updated, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the presence data has been updated, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Leave presence @@ -114,7 +114,7 @@ The `leave()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the user has left the presence set, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the user has left the presence set, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Get current presence members @@ -152,7 +152,7 @@ The `get()` method takes the following parameters: `List` -This is a suspend function. It returns a list of presence members currently in the room, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns a list of presence members currently in the room, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. @@ -160,7 +160,7 @@ This is a suspend function. It returns a list of presence members currently in t | --- | --- | --- | | clientId | The client ID of the present user. | String | | connectionId | The connection ID of the present user. | String | -| data | The presence data associated with the user, or `null`. | `JsonObject` | +| data | The presence data associated with the user. | `JsonObject?` | | extras | Additional data included with the presence message. | `JsonObject` | | updatedAt | When this presence state was last updated, in milliseconds since epoch. | Long | @@ -197,7 +197,7 @@ The `isUserPresent()` method takes the following parameters: `Boolean` -This is a suspend function. It returns `true` if the user is present or `false` otherwise, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It returns `true` if the user is present or `false` otherwise, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscribe to presence events @@ -268,7 +268,7 @@ Returns a `Subscription` object. #### Unsubscribe from presence events -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving presence events. diff --git a/src/pages/docs/chat/api/kotlin/room-reactions.mdx b/src/pages/docs/chat/api/kotlin/room-reactions.mdx index a937bf43f1..a53161fe3b 100644 --- a/src/pages/docs/chat/api/kotlin/room-reactions.mdx +++ b/src/pages/docs/chat/api/kotlin/room-reactions.mdx @@ -46,7 +46,7 @@ The `send()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the reaction has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the reaction has been sent, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscribe to room reactions @@ -109,7 +109,7 @@ Returns a `Subscription` object. #### Unsubscribe from room reactions -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving room reaction events. diff --git a/src/pages/docs/chat/api/kotlin/room.mdx b/src/pages/docs/chat/api/kotlin/room.mdx index c3a20dce9c..571550ef5c 100644 --- a/src/pages/docs/chat/api/kotlin/room.mdx +++ b/src/pages/docs/chat/api/kotlin/room.mdx @@ -33,7 +33,7 @@ The `Room` interface has the following properties: | typing | The Typing instance for typing indicators. | [Typing](/docs/chat/api/kotlin/typing) | | occupancy | The Occupancy instance for tracking user counts. | [Occupancy](/docs/chat/api/kotlin/occupancy) | | status | The current lifecycle status of the room. |
| -| error | The error information if the room is in a failed state, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | +| error | The error information if the room is in a failed state. | [ErrorInfo?](/docs/chat/api/kotlin/chat-client#errorinfo) | | options | The resolved configuration options for this room. | [RoomOptions](/docs/chat/api/kotlin/rooms#get) | | channel | The underlying Ably channel used for the room. Note: this property is experimental and may change in a future release. | RealtimeChannel | @@ -43,15 +43,15 @@ The `Room` interface has the following properties: | Status | Description | | --- | --- | -| 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 by a transition to `Attached`, `Suspended`, or `Failed`. | -| Attached | The room is attached and actively receiving events. In this status, clients 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 by a transition to `Detached` or `Failed`. | -| Detached | The room has been detached by the client and is no longer receiving events. | -| Suspended | The room, having previously been attached, has lost continuity. This typically occurs when the client is disconnected from Ably for more than two minutes. The client will automatically attempt to reattach when connectivity is restored. | -| Failed | An indefinite failure condition. This status is entered if an error is received from Ably, such as an attempt to attach without the necessary access rights. | -| Releasing | The room is being released and its resources are being cleaned up. Attempting to use a room in this state may result in undefined behavior. | -| Released | The room has been released and is no longer usable. A new room instance must be obtained to continue using the room. | +| Initialized | The room has been initialized, but no attach has been attempted yet. The value is `initialized`. | +| Attaching | An attach has been initiated by sending a request to Ably. This is a transient status and will be followed by a transition to `Attached`, `Suspended`, or `Failed`. The value is `attaching`. | +| Attached | The room is attached and actively receiving events. In this status, clients can publish and subscribe to messages, and enter the presence set. The value is `attached`. | +| 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 by a transition to `Detached` or `Failed`. The value is `detaching`. | +| Detached | The room has been detached by the client and is no longer receiving events. The value is `detached`. | +| Suspended | The room, having previously been attached, has lost continuity. This typically occurs when the client is disconnected from Ably for more than two minutes. The client will automatically attempt to reattach when connectivity is restored. The value is `suspended`. | +| Failed | An indefinite failure condition. This status is entered if an error is received from Ably, such as an attempt to attach without the necessary access rights. The value is `failed`. | +| Releasing | The room is being released and its resources are being cleaned up. Attempting to use a room in this state may result in undefined behavior. The value is `releasing`. | +| Released | The room has been released and is no longer usable. A new room instance must be obtained to continue using the room. The value is `released`. |
@@ -71,7 +71,7 @@ room.attach() `Unit` -This is a suspend function. It completes when the room is attached, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the room is attached, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. For more information, see [attach to a room](/docs/chat/rooms#attach). @@ -91,7 +91,7 @@ room.detach() `Unit` -This is a suspend function. It completes when the room is detached, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the room is detached, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. For more information, see [detach from a room](/docs/chat/rooms#detach). @@ -133,7 +133,7 @@ The `onStatusChange()` method takes the following parameters: | --- | --- | --- | | current | The new status of the room. | | | previous | The previous status of the room. |
| -| error | An error that provides a reason why the room has entered the new status, if applicable, or `null`. | [ErrorInfo](/docs/chat/api/kotlin/chat-client#errorinfo) | +| error | An error that provides a reason why the room has entered the new status, if applicable. | [ErrorInfo?](/docs/chat/api/kotlin/chat-client#errorinfo) |
@@ -145,7 +145,7 @@ Returns a `Subscription` object. #### Deregister the listener -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to deregister the room status listener. @@ -195,7 +195,7 @@ Returns a `Subscription` object. #### Deregister the listener -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to deregister the discontinuity listener. diff --git a/src/pages/docs/chat/api/kotlin/rooms.mdx b/src/pages/docs/chat/api/kotlin/rooms.mdx index f390f2e76c..302a15b6d3 100644 --- a/src/pages/docs/chat/api/kotlin/rooms.mdx +++ b/src/pages/docs/chat/api/kotlin/rooms.mdx @@ -87,7 +87,7 @@ The `get()` method takes the following parameters: | typing | Optional | Configuration for typing indicators. | | | presence | Optional | Configuration for presence events. |
| | occupancy | Optional | Configuration for occupancy events. |
| -| messages | Optional | Configuration for message reactions. |
| +| messages | Optional | Configuration for messages. |
| | reactions | Optional | Configuration for room reactions. | RoomReactionsOptions |
@@ -139,7 +139,7 @@ The `get()` method takes the following parameters: [`Room`](/docs/chat/api/kotlin/room) -This is a suspend function. It returns the new or existing [`Room`](/docs/chat/api/kotlin/room) instance, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo). It also throws if the room already exists with different options, or if [`release()`](#release) is called before `get()` returns. +This is a suspend function. It returns the new or existing [`Room`](/docs/chat/api/kotlin/room) instance, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception). It also throws if the room already exists with different options, or if [`release()`](#release) is called before `get()` returns. ## Release a room @@ -171,7 +171,7 @@ The `release()` method takes the following parameters: `Unit` -This is a suspend function. It completes when the room is fully released, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the room is fully released, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscription diff --git a/src/pages/docs/chat/api/kotlin/typing.mdx b/src/pages/docs/chat/api/kotlin/typing.mdx index b2e7998427..4bbe53655f 100644 --- a/src/pages/docs/chat/api/kotlin/typing.mdx +++ b/src/pages/docs/chat/api/kotlin/typing.mdx @@ -45,7 +45,7 @@ room.typing.keystroke() `Unit` -This is a suspend function. It completes when the typing event has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the typing event has been sent, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Stop typing @@ -68,7 +68,7 @@ room.typing.stop() `Unit` -This is a suspend function. It completes when the stop event has been sent, or throws an [`ErrorInfo`](/docs/chat/api/kotlin/chat-client#errorinfo) on failure. +This is a suspend function. It completes when the stop event has been sent, or throws a [`ChatException`](/docs/chat/api/kotlin/chat-client#chatexception) on failure. ## Subscribe to typing events @@ -137,7 +137,7 @@ Returns a `Subscription` object. #### Unsubscribe from typing events -subscription.unsubscribe(): Unit +{`subscription.unsubscribe(): Unit`} Call `unsubscribe()` to stop receiving typing events.