Rooms

Rooms are used to organize and logically separate your users and chat messages into ‘rooms’. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators. A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users.

You also control which features are enabled in a room when you create one. For instance, you might only want to utilize typing indicators in direct messages between users.

Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing are configured as part of a room’s options.

A room is created, or an existing one is retrieved from the rooms collection using the rooms.get() method:

JavaScript
Select...

const room = chatClient.rooms.get('basketball-stream');

Copy
Copied!

When you create or retrieve a room using rooms.get(), you need to choose which additional chat features you want enabled for that room. This is configured by passing a RoomOptions object as the second argument. In addition to setting which features are enabled, RoomOptions also configures the properties of the associated features, such as the timeout period for typing indicators.

JavaScript
Select...

const room = chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy});

Copy
Copied!

You can also use the RoomOptionsDefaults property for each RoomOption to configure whether the default settings should be used:

JavaScript
Select...

const room = chatClient.rooms.get('basketball-stream', {presence: RoomOptionsDefaults.presence});

Copy
Copied!

Or configure each feature using your own values:

JavaScript
Select...

const room = chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});

Copy
Copied!

Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages:

Releasing a room allows the underlying resources to be garbage collected or released. Once rooms.release() has been called, the room will be unusable and a new instance will need to be created using rooms.get() if you want to reuse it.

Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it is may be more beneficial.

JavaScript
Select...

await rooms.release('basketball-stream');

Copy
Copied!

Once a reference to a room has been created using rooms.get(), clients attach to it in order to ensure it is created in the Ably system.

As soon as a client is attached, Ably will begin streaming messages and events to them, regardless of whether or not they have registered any listeners to receive those messages and events.

Use the attach() method on a room to attach to it:

JavaScript
Select...

await room.attach();

Copy
Copied!

Use the detach() method on a room to detach from it and stop receiving messages and events:

JavaScript
Select...

await room.detach();

Copy
Copied!

If a client detaches from a room without de-registering any of their listeners, they can subsequently re-attach at a later point and their listeners will continue to receive messages and events.

Monitoring the status of a room enables you to track its lifecycle and react accordingly.

A room can have any of the following statuses:

Use the current property to check which status a room is currently in:

JavaScript
Select...

const currentStatus = room.status.current

Copy
Copied!

You can also subscribe to room status updates by registering a listener. An event will be emitted whenever the status of the room changes.

Use the room.status.onChange() method in a room to register a listener for status change updates:

JavaScript
Select...

const { off } = room.onStatusChange((change) =>
console.log(change));

Copy
Copied!

To remove the room status listener, call the provided off() function:

JavaScript
Select...

off();

Copy
Copied!

Use the room.status.offAll() method to remove all room status listeners in a room:

JavaScript
Select...

room.status.offAll();

Copy
Copied!