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.
Create or retrieve a room
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:
const room = await chatClient.rooms.get('basketball-stream', AllFeaturesEnabled);
CopyCopied!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.
const presence = {enter: false};
const reactions = {};
const occupancy = {};
const typing = {timeoutMs: 5000};
const room = await chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy});
CopyCopied!You can also use the AllFeaturesEnabled property for each RoomOption to configure whether preconfigured example settings should be used:
const room = await chatClient.rooms.get('basketball-stream', {presence: AllFeaturesEnabled.presence});
CopyCopied!Or configure each feature using your own values:
const room = await chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});
CopyCopied!Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages:
| Feature | RoomOption | Default settings |
| Presence | presence | AllFeaturesEnabled.presence |
| Occupancy | occupancy | AllFeaturesEnabled.occupancy |
| Typing indicators | typing | AllFeaturesEnabled.typing |
| Room reactions | reactions | AllFeaturesEnabled.reactions |
Release a room
Releasing a room allows the underlying resources to be garbage collected or released.
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.
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.
Note that any unresolved promises from rooms.get() will be rejected when rooms.release() is called.
await rooms.release('basketball-stream');
CopyCopied!Attach to a room
As soon as a client is attached to a room, 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.
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.
Use the attach() method on a room to attach to it:
await room.attach();
CopyCopied!Detach from a room
Use the detach() method on a room to detach from it and stop receiving messages and events:
await room.detach();
CopyCopied!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.
Room status
Monitoring the status of a room enables you to track its lifecycle and react accordingly.
A room can have any of the following statuses:
| Status | Description |
|---|---|
| initializing | The library is initializing the room. This status is only used for React when the room has not yet resolved. |
| initialized | The room has been initialized, but no attach has been attempted yet. |
| attaching | An attach has been initiated by sending a request to Ably. This is a transient status and will be followed either by a transition to attached, suspended, or failed. |
| attached | An attach has succeeded. In the attached status a client can publish and subscribe to messages, and enter the presence set. |
| detaching | A detach has been initiated on the attached room by sending a request to Ably. This is a transient status and will be followed either by a transition to detached or failed. |
| detached | The room has been detached by the client. |
| suspended | The room, having previously been attached, has lost continuity. This is normally due to the client being disconnected from Ably for more than two minutes. The client will automatically attempt to reattach as soon as connectivity is restored. |
| failed | An indefinite failure condition. This status is entered if an error has been received from Ably, such as an attempt to attach without the necessary access rights. |
Use the status property to check which status a room is currently in:
const currentStatus = room.status;
// The error related to the current room status
const currentError = room.error;
CopyCopied!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.onStatusChange() method in a room to register a listener for status change updates:
const { off } = room.onStatusChange((change) =>
console.log(change));
CopyCopied!Use the off() function returned in the onStatusChange() response to remove a room status listener:
off();
CopyCopied!Use the room.offAllStatusChange() method to remove all room status listeners in a room:
room.offAllStatusChange();
CopyCopied!