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 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:

JavaScript
Select...

const { unsubscribe } = room.presence.subscribe((event) => {
  console.log(`${event.clientId} entered with data: ${event.data}`);
});

Copy
Copied!

You can also subscribe to only specific presence events, or an array of presence events:

JavaScript
Select...

// 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}`);
});

Copy
Copied!

The following is the structure of a presence event:

{
  "clientId": "clemons123",
  "data": "Be right back!",
  "timestamp": 1677595689759,
  "action": "update"
}

Copy
Copied!

The following are the properties of a presence event:

Unsubscribe from online presence to remove previously registered listeners.

Use the unsubscribe() function returned in the subscribe() response to remove a listener:

JavaScript
Select...

// Initial subscription
const { unsubscribe } = room.presence.subscribe((event) => {
  console.log(`${event.clientId} entered with data: ${event.data}`);
});


// To remove the listener
unsubscribe();

Copy
Copied!

Use the presence.unsubscribeAll() method to remove all presence listeners in a room:

JavaScript
Select...

await room.presence.unsubscribeAll();

Copy
Copied!

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:

JavaScript
Select...

await room.presence.enter({ status: 'available' });

Copy
Copied!

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 ao all users subscribed to presence:

JavaScript
Select...

await room.presence.update({ status: 'busy' });

Copy
Copied!

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’.

When a user goes offline or closes their connection, a leave event is also emitted and they are removed from the presence set.

JavaScript
Select...

await room.presence.leave({ status: 'Be back later!' });

Copy
Copied!

When creating a room there are two options that can be set for the presence feature:

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:

JavaScript
Select...

// 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' });

Copy
Copied!

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:

JavaScript
Select...

const isPresent = await room.presence.isUserPresent('clemons123');

Copy
Copied!

The following is the structure of an individual presence member within the presence set:

{
  "action": "enter",
  "clientId": "clemons123",
  "data": "Good morning!",
  "extras": "",
  "updatedAt": 1677595689759
}

Copy
Copied!

The following are the properties of an individual presence member: