Presence

The presence feature of a chat room enables online users to advertise to others that they are online. Use this feature to build online status indicators to display who is online in a chat room. Users can also share additional information such as avatar URLs or custom statuses.

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:

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

Presence event structure

The following is the structure of a presence event:

JSON

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:

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

JavaScript

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:

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:

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.

Presence options

The following options can be set when creating a room that are specific to presence:

Property	Description	Default
enableEvents	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:

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:

Presence member structure

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