Online status
Subscribe to the online status of room members using the presence feature. Presence enables you to show which members are currently online, indicate when a user goes offline, and have users optionally set additional information about their profile, or their current status within the application.
Subscribe to presence
Subscribe to users’ presence status by registering a listener. Presence events are emitted whenever a member enters or leaves the presence set, or updates their user data. Use the presence.subscribe() method in a room to receive updates:
const { unsubscribe } = room.presence.subscribe((event) => {
console.log(`${event.clientId} entered with data: ${event.data}`);
});
CopyCopied!You can also subscribe to only specific presence events, or an array of presence events:
// Subscribe to only 'enter' events:
const { unsubscribe } = room.presence.subscribe('enter', (event) => {
console.log(`${event.clientId} entered with data: ${event.data}`);
});
// Subscribe to 'update' and 'leave' events:
const { unsubscribe } = room.presence.subscribe(['update', 'leave'], (event) => {
console.log(`${event.clientId} entered with data: ${event.data}`);
});
CopyCopied!Presence event structure
The following is the structure of a presence event:
{
"clientId": "clemons123",
"data": "Be right back!",
"timestamp": 1677595689759,
"action": "update"
}
CopyCopied!The following are the properties of a presence event:
| Property | Description | Type |
|---|---|---|
| clientId | The ID of the client that triggered the event. | String |
| data | Optional user data. | Object |
| timestamp | The time that the event was emitted. | Number |
| action | The type of presence action that called the event. One of either present, enter, update or leave. | PresenceEvents |
Unsubscribe from presence
Use the unsubscribe() function returned in the subscribe() response to remove a presence listener:
// Initial subscription
const { unsubscribe } = room.presence.subscribe((event) => {
console.log(`${event.clientId} entered with data: ${event.data}`);
});
// To remove the listener
unsubscribe();
CopyCopied!Use the presence.unsubscribeAll() method to remove all presence listeners in a room:
await room.presence.unsubscribeAll();
CopyCopied!Set user presence
Users can enter and leave the presence set of a room to indicate when they are online or offline. They can also set user data when entering and leaving the set, such as their current status. Presence is also linked to a user’s connection status. For example, if a user goes offline then a leave event will be emitted for them.
Use the presence.enter() method to indicate when a user joins a room. This will send a presence event to all users subscribed to presence indicating that a new member has joined the chat. You can also set an optional data field with information such as the status of a user:
await room.presence.enter({ status: 'available' });
CopyCopied!Use the presence.update() method when a user wants to update their data, such as an update to their status, or to indicate that they’re raising their hand. Updates will send a presence event to all users subscribed to presence:
await room.presence.update({ status: 'busy' });
CopyCopied!Use the presence.leave() method to explicitly remove a user from the presence set. This will send a presence event to all users subscribed to presence. You can also set an optional data field such as setting a status of ‘Back later’.
await room.presence.leave({ status: 'Be back later!' });
CopyCopied!When a user goes offline or closes their connection, a leave event is also emitted and they are removed from the presence set.
Presence options
The following options can be set when creating a room that are specific to presence:
| Property | Description | Default |
|---|---|---|
| enter | Set whether the client has permissions to enter the presence set. Calling presence.enter() is still required. | true |
| subscribe | Set whether the client has permissions to subscribe to the presence set. Calling presence.subscribe() is still required. | true |
Retrieve the presence set
The online presence of users can be retrieved in one-off calls. This can be used to check the status of an individual user, or return the entire presence set as an array.
Use the presence.get() method to retrieve an array of all users currently entered into the presence set, or individual users:
// Retrieve all users entered into presence as an array:
const presentMembers = await room.presence.get();
// Retrieve the status of specific users by their clientId:
const presentMember = await room.presence.get({ clientId: 'clemons123' });
CopyCopied!Alternatively, use the presence.isUserPresent() method and pass in a user’s clientId to check whether they are online or not. This will return a boolean:
const isPresent = await room.presence.isUserPresent('clemons123');
CopyCopied!Presence member structure
The following is the structure of an individual presence member within the presence set:
{
"action": "enter",
"clientId": "clemons123",
"data": "Good morning!",
"extras": "",
"updatedAt": 1677595689759
}
CopyCopied!The following are the properties of an individual presence member:
| Property | Description | Type |
|---|---|---|
| action | The latest type of presence action the presence user has. One of either present, enter, update or leave. | PresenceEvents |
| clientId | The ID of the client this event relates to. | String |
| data | The latest optional user data associated with the user. | Object |
| extras | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads related to the user’s latest presence event. | Any |
| updatedAt | The time of the last presence event. | Number |