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.
Relationship between rooms and channels
It is important to note that each room is backed by a single Ably Pub/Sub channel. You may need to be aware of this when using some integrations with Ably, such as the Pulsar connectors, or if you are operating in an environment where a Chat SDK is not available.
The channel name is the same as the room ID with an appended suffix of ::$chat (e.g some-room-id::$chat). In most cases, you will not need to worry about this, as the Chat SDK handles the channel creation and management for you and capabilities can be configured at the room level.
Create or retrieve a room
Users send messages to a room and subscribe to the room in order to receive messages.
A room is created, or an existing one is retrieved from the rooms collection using the rooms.get() method:
When you create or retrieve a room using rooms.get(), you can provide custom configuration for some features for that room by passing a RoomOptions object as the second argument. If you do not provide a RoomOptions object, the default settings will be used.
The details of the options available to each feature are documented on their respective pages:
| Feature | RoomOption | Default settings |
|---|---|---|
| Presence | presence.enableEvents | true |
| Occupancy | occupancy.enableEvents | false |
| Typing indicators | typing.heartbeatThrottleMs | 10000 |
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 may be more beneficial. Also, proactively disconnecting rather than waiting for the standard two-minute timeout can help reduce costs and improve performance.
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.
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:
Detach from a room
Use the detach() method on a room to detach from it and stop receiving messages and events:
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:
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:
Use the off() function returned in the onStatusChange() response to remove a room status listener:
Use the room.offAllStatusChange() method to remove all room status listeners in a room: