User Presence

Track real-time user online/offline status and configure presence subscriptions using the CometChat JavaScript SDK.

Quick Reference for AI Agents & Developers

// Subscribe to presence during init
const appSettings = new CometChat.AppSettingsBuilder()
  .subscribePresenceForAllUsers()  // or .subscribePresenceForRoles([]) / .subscribePresenceForFriends()
  .setRegion("REGION").build();

// Listen for presence changes
CometChat.addUserListener("LISTENER_ID", new CometChat.UserListener({
  onUserOnline: (user) => console.log("Online:", user),
  onUserOffline: (user) => console.log("Offline:", user)
}));

// Remove listener
CometChat.removeUserListener("LISTENER_ID");

User Presence helps us understand if a user is available to chat or not.

Available via: SDK | REST API | UI Kits

Real-time Presence

In other words, as a logged-in user, how do I know if a user is online or offline?

Based on the settings provided in the AppSettings class while initialising the SDK using the init() method, the logged-in user will receive the presence for the other users in the app.

In the AppSettings class, you can set the type of Presence you wish to receive for that particular session of the app.

For presence subscription, the AppSettingsBuilder provides 3 methods :

• subscribePresenceForAllUsers() - this will inform the logged-in user when any user in the app comes online or goes offline
• subscribePresenceForRoles(Array roles) - This will inform the logged-in user, only when the users with the specified roles come online or go offline.
• subscribePresenceForFriends() - This will inform the logged-in user, only when either of his friends come online or go offline.

If none of the above methods are used, no presence will be sent to the logged-in user.

You must configure presence subscription in AppSettings during CometChat.init() before any presence events will be delivered. See Setup SDK for details.

You need to register the UserListener using the addUserListener() method where ever you wish to receive these events in.

JavaScript

let listenerID = "UNIQUE_LISTENER_ID";

CometChat.addUserListener(
  listenerID,
  new CometChat.UserListener({
    onUserOnline: onlineUser => {
      console.log("On User Online:", { onlineUser });
    },
    onUserOffline: offlineUser => {
      console.log("On User Offline:", { offlineUser });
    }
  })
);

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";

CometChat.addUserListener(
  listenerID,
  new CometChat.UserListener({
    onUserOnline: (onlineUser: CometChat.User) => {
      console.log("On User Online:", { onlineUser });
    },
    onUserOffline: (offlineUser: CometChat.User) => {
      console.log("On User Offline:", { offlineUser });
    }
  })
);

Parameter	Description
listenerID	An ID that uniquely identifies that listener.

You will receive an object of the User class in the listener methods.

Listener Cleanup: Always remove the listener when the component or view is unmounted/destroyed to prevent memory leaks and duplicate callbacks. Use CometChat.removeUserListener(listenerID) in your cleanup logic.

JavaScript

let listenerID = "UNIQUE_LISTENER_ID";
CometChat.removeUserListener(listenerID);

TypeScript

let listenerID: string = "UNIQUE_LISTENER_ID";
CometChat.removeUserListener(listenerID);

Always remove your UserListener when the component or view unmounts to prevent memory leaks and duplicate event handling.

CometChat.removeUserListener("LISTENER_ID");

User List Presence

In other words, as a logged-in user, when I retrieve the user list, how do I know if a user is online/offline?

When you fetch the list of users, in the User object, you will receive 2 fields

1. status - This will hold either of the two values :

• online - This indicates that the user is currently online and available to chat.
• offline - This indicates that the user is currently offline and is not available to chat.

2. lastActiveAt - in case the user is offline, this field holds the timestamp of the time when the user was last online. This can be used to display the Last seen of the user if need be.

Best Practices

Practice	Details
Choose the right subscription	Use subscribePresenceForFriends() or subscribePresenceForRoles() instead of subscribePresenceForAllUsers() in apps with many users to reduce unnecessary events
Unique listener IDs	Use unique, descriptive listener IDs (e.g., "chat-screen-presence") to avoid accidentally overwriting other listeners
Cleanup on unmount	Always call removeUserListener() when the component/view is destroyed
Combine with user list	Use the status field from UsersRequest results for initial state, then update via UserListener for real-time changes

Troubleshooting

Symptom	Cause	Fix
No presence events received	Presence subscription not configured in AppSettings	Add subscribePresenceForAllUsers(), subscribePresenceForRoles(), or subscribePresenceForFriends() to your AppSettingsBuilder
Presence events stop after navigation	Listener was removed or component unmounted	Re-register the listener when the component mounts again
Duplicate presence events	Multiple listeners registered with the same or different IDs	Ensure you remove old listeners before adding new ones
lastActiveAt is 0 or null	User has never been online or data not yet available	Handle this case in your UI with a fallback like “Never active”

Next Steps

Retrieve Users

Fetch user lists with filtering and pagination.

User Management

Create and update users programmatically.

Connection Status

Monitor SDK connection to CometChat servers.

All Real-time Listeners

Overview of all available real-time listeners.