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() method to obtain a room instance:
1
val room = chatClient.rooms.get("my-room")For more information, see the rooms documentation.
Properties
The Room interface has the following properties:
nameStringmessagesMessagespresencePresencereactionsRoomReactionstypingTypingoccupancyOccupancystatusRoomStatuserrorErrorInfo?optionsRoomOptionschannelRealtimeChannelAttach to a room
suspend room.attach(): UnitAttach to the room to start receiving messages and events. Attaching is required before the client can publish or subscribe to room events.
1
room.attach()Returns
Unit
This is a suspend function. It completes when the room is attached, or throws a ChatException on failure.
For more information, see attach to a room.
Detach from a room
suspend room.detach(): UnitDetach from the room to stop receiving messages and events. Existing subscriptions are preserved but will not receive events until the room is re-attached.
1
room.detach()Returns
Unit
This is a suspend function. It completes when the room is detached, or throws a ChatException on failure.
For more information, see detach from a room.
Subscribe to room status changes
room.onStatusChange(listener: RoomStatusListener): SubscriptionRegister a listener to receive room status change events. The listener is called whenever the room transitions between lifecycle states.
1
2
3
4
5
6
7
8
9
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:
listenerrequiredRoomStatusChangeReturns
Returns a Subscription object.
Deregister the listener
subscription.unsubscribe(): UnitCall unsubscribe() to deregister the room status listener.
Subscribe to discontinuity events
room.onDiscontinuity(listener: DiscontinuityListener): SubscriptionRegister 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.
1
2
3
4
5
6
7
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:
listenerrequiredDiscontinuityListenerReturns
Returns a Subscription object.
Deregister the listener
subscription.unsubscribe(): UnitCall unsubscribe() to deregister the discontinuity listener.
Collect room status changes as a Flow
Room.statusAsFlow(): Flow<RoomStatusChange>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.
1
2
3
4
5
6
7
import kotlinx.coroutines.launch
launch {
room.statusAsFlow().collect { change ->
println("Room status: ${change.current}")
}
}Returns
Flow<RoomStatusChange>
Returns a Flow that emits RoomStatusChange events. The flow automatically manages the underlying subscription.
Collect discontinuity events as a Flow
Room.discontinuityAsFlow(): Flow<ErrorInfo>Returns a Kotlin Flow that emits discontinuity events. This is an extension function on the Discontinuity interface (which Room extends) that provides a reactive alternative to listener-based subscriptions.
1
2
3
4
5
6
7
import kotlinx.coroutines.launch
launch {
room.discontinuityAsFlow().collect { error ->
println("Discontinuity detected: $error")
}
}Returns
Flow<ErrorInfo>
Returns a Flow that emits ErrorInfo events when discontinuities occur. The flow automatically manages the underlying subscription.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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()