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
const room = await chatClient.rooms.get('my-room');For more information, see the rooms documentation.
Properties
The Room interface has the following properties:
nameStringmessagesMessagespresencePresencereactionsRoomReactionstypingTypingoccupancyOccupancystatusRoomStatuserrorErrorInfo or UndefinedchannelAbly.RealtimeChannelAttach to a room
room.attach(): Promise<void>Attach to the room to start receiving messages and events. Attaching is required before the client can publish or subscribe to room events.
1
await room.attach();Returns
Promise<void>
Returns a promise. The promise is fulfilled when the room is attached, or rejected with an ErrorInfo object.
For more information, see attach to a room.
Detach from a room
room.detach(): Promise<void>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.
1
await room.detach();Returns
Promise<void>
Returns a promise. The promise is fulfilled when the room is detached, or rejected with an ErrorInfo object.
For more information, see detach from a room.
Get room options
room.options(): RoomOptionsReturns a deep copy of the room configuration options.
1
2
const options = room.options();
console.log(options.typing?.heartbeatThrottleMs);Returns
RoomOptions
Returns a deep copy of the room's configuration options.
typingoptionalTypingOptionspresenceoptionalPresenceOptionsoccupancyoptionalOccupancyOptionsmessagesoptionalMessagesOptionsSubscribe to room status changes
room.onStatusChange(listener: RoomStatusListener): StatusSubscriptionRegister 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
const { off } = room.onStatusChange((change) => {
console.log(`Room status changed to: ${change.current}`);
if (change.error) {
console.error('Error:', change.error);
}
});
// To remove the listener
off();Parameters
The onStatusChange() method takes the following parameters:
listenerrequiredRoomStatusChangeReturns
StatusSubscription
Returns an object with the following methods:
Deregister the listener
off(): voidCall off() to deregister the room status listener.
Subscribe to discontinuity events
room.onDiscontinuity(handler: DiscontinuityListener): StatusSubscriptionRegister 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
const { off } = room.onDiscontinuity((reason) => {
console.log('Discontinuity detected:', reason);
// You may want to re-fetch recent messages here
});
// To remove the listener
off();Parameters
The onDiscontinuity() method takes the following parameters:
handlerrequiredDiscontinuityListenerReturns
StatusSubscription
Returns an object with the following methods:
Deregister the listener
off(): voidCall off() to deregister the discontinuity listener.
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
const room = await chatClient.rooms.get('my-room');
// Attach to start receiving events
await room.attach();
// Monitor room status
const { off: offStatus } = room.onStatusChange((change) => {
console.log(`Room status: ${change.current}`);
});
// Monitor for discontinuities
const { off: offDiscontinuity } = room.onDiscontinuity((reason) => {
console.log('Discontinuity detected, consider re-fetching messages');
});
// Access room features
const messages = room.messages;
const presence = room.presence;
const typing = room.typing;
// Get the room name
console.log('Room name:', room.name);
// When done, detach and clean up
await room.detach();
offStatus();
offDiscontinuity();