User Presence - CometChat Docs

Quick Reference for AI Agents & Developers

Subscribe presence: AppSettings.AppSettingsBuilder().subscribePresenceForAllUsers() or .subscribePresenceForFriends() or .subscribePresenceForRoles(_:)
Listen for presence: onUserOnline(_:), onUserOffline(_:) in CometChatUserDelegate
User status: user.status — .online or .offline
Last active: user.lastActiveAt — timestamp of last activity
Related: Retrieve Users · Connection Status · Users Overview

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

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

Presence Subscription

Configure presence subscription during SDK initialization using AppSettings.

Swift

// Subscribe to ALL Users
let appSettings = AppSettings.AppSettingsBuilder()
    .subscribePresenceForAllUsers()
    .setRegion(region: "us")
    .build()

CometChat.init(appId: APP_ID, appSettings: appSettings, onSuccess: { success in
    print("CometChat initialized with presence for all users")
}, onError: { error in
    print("Error: \(error.errorDescription)")
})

AppSettingsBuilder Subscription Methods

Method	Returns	Description
`subscribePresenceForAllUsers()`	AppSettingsBuilder	Subscribe to presence updates for all users in the app
`subscribePresenceForFriends()`	AppSettingsBuilder	Subscribe to presence updates for friends only
`subscribePresenceForRoles(_:)`	AppSettingsBuilder	Subscribe to presence updates for users with specific roles

Sample Payload - AppSettingsBuilder

Builder Configuration:

Parameter	Type	Description
subscribePresenceForAllUsers	Method	Subscribes to presence updates for all users in the app. Example: `.subscribePresenceForAllUsers()`
subscribePresenceForFriends	Method	Subscribes to presence updates for friends only. Example: `.subscribePresenceForFriends()`
subscribePresenceForRoles	Method	Subscribes to presence updates for users with specific roles. Example: `.subscribePresenceForRoles(roles: ["admin", "moderator"])`
setRegion	Method	Sets the region for the CometChat app. Example: `.setRegion(region: "us")`

Subscription Examples:

Use Case	Builder Configuration
Subscribe to all users	`.subscribePresenceForAllUsers().setRegion(region: "us").build()`
Subscribe to friends only	`.subscribePresenceForFriends().setRegion(region: "us").build()`
Subscribe to specific roles	`.subscribePresenceForRoles(roles: ["admin", "moderator"]).setRegion(region: "us").build()`

If none of the subscription methods are used, NO presence updates will be sent
Subscription is set per session (app launch)
Must be configured BEFORE CometChat.init()

Swift

let appSettings = AppSettings.AppSettingsBuilder()
    .subscribePresenceForFriends()
    .setRegion(region: "us")
    .build()

Swift

let appSettings = AppSettings.AppSettingsBuilder()
    .subscribePresenceForRoles(roles: ["admin", "moderator"])
    .setRegion(region: "us")
    .build()

CometChatUserDelegate

Listen for real-time presence updates by conforming to CometChatUserDelegate.

Swift
Objective C

class ViewController: UIViewController, CometChatUserDelegate {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CometChat.userdelegate = self
    }
    
    // Called when a user comes online
    func onUserOnline(user: User) {
        print("\(user.name ?? "") is now online")
    }
    
    // Called when a user goes offline
    func onUserOffline(user: User) {
        print("\(user.name ?? "") is now offline")
    }
}

@interface ViewController ()<CometChatUserDelegate>

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    [CometChat setUserdelegate:self];
}

- (void)onUserOfflineWithUser:(User * _Nonnull)user {
    
    NSLog(@"%@ status becomes offline.",[user stringValue]);
}

- (void)onUserOnlineWithUser:(User * _Nonnull)user {
    
    NSLog(@"%@ status becomes online.",[user stringValue]);
}

Delegate Methods

Method	Parameter	Description
`onUserOnline(user:)`	User	Called when a subscribed user comes online
`onUserOffline(user:)`	User	Called when a subscribed user goes offline

Sample Payload - onUserOnline Event

Event Trigger: Received via CometChatUserDelegate.onUserOnline(user:)User Object Properties:

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"user123"`
name	String?	Display name of the user. Example: `"John Doe"`
avatar	String?	URL to the user’s avatar image. Example: `"https://example.com/avatar.png"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user. Example: `"default"`
status	UserStatus	Current online status of the user. Example: `.online`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1699900000.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Sample Payload - onUserOffline Event

Event Trigger: Received via CometChatUserDelegate.onUserOffline(user:)User Object Properties:

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"user123"`
name	String?	Display name of the user. Example: `"John Doe"`
avatar	String?	URL to the user’s avatar image. Example: `"https://example.com/avatar.png"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user. Example: `"default"`
status	UserStatus	Current online status of the user. Example: `.offline`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1699900300.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Set delegate in viewDidLoad(): CometChat.userdelegate = self
Only receives updates for subscribed users (based on AppSettings)
Remove delegate when view is dismissed to avoid memory leaks

Start Listening for Presence

Swift

CometChat.userdelegate = self
// This class now conforms to CometChatUserDelegate
// Will receive onUserOnline and onUserOffline callbacks

Sample Payload - Start Listening

Setup Configuration:

Parameter	Type	Description
userdelegate	CometChatUserDelegate	Reference to the delegate object. Example: `self`

Listening Status:

Parameter	Type	Description
status	String	Current listening state. Example: `"Listening for presence updates"`
delegate	CometChatUserDelegate	Active delegate receiving events. Example: `ViewController.self`

Events Waiting:

Event	Description
onUserOnline(user:)	Triggered when a subscribed user comes online
onUserOffline(user:)	Triggered when a subscribed user goes offline

Stop Listening for Presence

Swift

CometChat.userdelegate = nil

Sample Payload - Stop Listening

Cleanup Configuration:

Parameter	Type	Description
userdelegate	CometChatUserDelegate?	Set to nil to stop receiving events. Example: `nil`

Listening Status:

Parameter	Type	Description
status	String	Current listening state. Example: `"No longer listening for presence updates"`

Check User Status

Swift

CometChat.getUser(UID: "cometchat-uid-2", onSuccess: { user in
    let status = user?.status // .online or .offline
    let lastActive = user?.lastActiveAt // Unix timestamp
}, onError: { error in
    print("Error: \(error?.errorDescription)")
})

Sample Payload - Check User Status

Request Parameters:

Parameter	Type	Description
UID	String	Unique identifier of the user to check. Example: `"cometchat-uid-2"`

Success Response (User Object):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-2"`
name	String?	Display name of the user. Example: `"George Alan"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user. Example: `"default"`
status	UserStatus	Current online status of the user. Example: `.online`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1772110483.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code identifying the error type. Example: `"ERR_UID_NOT_FOUND"`
errorDescription	String	Human-readable description of the error. Example: `"User with the specified UID does not exist"`

Get Online Users

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
    .set(limit: 30)
    .set(status: .online)
    .build()

usersRequest.fetchNext(onSuccess: { users in
    // All users in this list are online
}, onError: { error in
    print("Error: \(error?.errorDescription)")
})

Sample Payload - Get Online Users

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of users to fetch. Example: `30`
status	UserStatus	Filter by online status. Example: `.online`

Success Response (Array of User Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-1"`
name	String?	Display name of the user. Example: `"Andrew Joseph"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user. Example: `"admin"`
status	UserStatus	Current online status of the user. Example: `.online`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity. Example: `1772105474.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: `"[User]"`
count	Int	Number of users returned. Example: `5`
filter	String	Applied filter. Example: `"status = .online"`

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code identifying the error type. Example: `"ERR_NOT_LOGGED_IN"`
errorDescription	String	Human-readable description of the error. Example: `"User is not logged in"`

Get Offline Users

Swift

let usersRequest = UsersRequest.UsersRequestBuilder()
    .set(limit: 30)
    .set(status: .offline)
    .build()

usersRequest.fetchNext(onSuccess: { users in
    for user in users {
        let lastSeen = user.lastActiveAt // When user was last online
    }
}, onError: { error in
    print("Error: \(error?.errorDescription)")
})

Sample Payload - Get Offline Users

Request Parameters:

Parameter	Type	Description
limit	Int	Maximum number of users to fetch. Example: `30`
status	UserStatus	Filter by offline status. Example: `.offline`

Success Response (Array of User Objects):

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"cometchat-uid-1"`
name	String?	Display name of the user. Example: `"Andrew Joseph"`
avatar	String?	URL to the user’s avatar image. Example: `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"`
link	String?	URL to the user’s profile page. Example: `nil`
role	String?	Role assigned to the user. Example: `"admin"`
status	UserStatus	Current online status of the user. Example: `.offline`
statusMessage	String?	Custom status message set by the user. Example: `nil`
lastActiveAt	Double	Unix timestamp of the user’s last activity (use for “last seen”). Example: `1772105474.0`
hasBlockedMe	Bool	Indicates if this user has blocked the logged-in user. Example: `false`
blockedByMe	Bool	Indicates if the logged-in user has blocked this user. Example: `false`
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active). Example: `0.0`
tags	[String]	Array of tags associated with the user. Example: `[]`
metadata	[String: Any]?	Custom metadata dictionary. Example: `[:]`

Response Summary:

Parameter	Type	Description
type	String	Response type. Example: `"[User]"`
count	Int	Number of users returned. Example: `30`
filter	String	Applied filter. Example: `"status = .offline"`

Sample User Entries:

uid	name	status	lastActiveAt
123	Abc	.offline	1756196135.0 (26/08/25, 1:45 PM)
123abc	Abc	.offline	1753957273.0 (31/07/25, 3:51 PM)
user177193848825	aditya	.offline	1771941423.0 (24/02/26, 7:27 PM)
cometchat-uid-1	Andrew Joseph	.offline	1772105474.0 (26/02/26, 5:01 PM)
cometchat-uid-5	John Paul	.offline	1771416145.0 (18/02/26, 6:32 PM)

Error Response (CometChatException):

Parameter	Type	Description
errorCode	String	Unique error code identifying the error type. Example: `"ERR_NOT_LOGGED_IN"`
errorDescription	String	Human-readable description of the error. Example: `"User is not logged in"`

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:

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

Sample Payload - User List with Presence

User Object with Presence Data:

Parameter	Type	Description
uid	String?	Unique identifier of the user. Example: `"user1"`
name	String?	Display name of the user. Example: `"Alice"`
avatar	String?	URL to the user’s avatar image. Example: `"https://example.com/alice.png"`
status	UserStatus	Current online status. Example: `.online`
lastActiveAt	Double	Unix timestamp of last activity. Example: `1699900000.0`

Multiple Users Example:

uid	name	status	lastActiveAt	Description
user1	Alice	.online	1699900000.0	Currently online
user2	Bob	.offline	1699800000.0	Last seen timestamp

Calculating “Last Seen”

Swift

if user.status == .offline {
    let lastActiveDate = Date(timeIntervalSince1970: user.lastActiveAt)
    let timeAgo = Date().timeIntervalSince(lastActiveDate)
    
    let minutes = Int(timeAgo / 60)
    let hours = Int(timeAgo / 3600)
    let days = Int(timeAgo / 86400)
    
    if days > 0 {
        print("Last seen \(days) day(s) ago")
    } else if hours > 0 {
        print("Last seen \(hours) hour(s) ago")
    } else {
        print("Last seen \(minutes) minute(s) ago")
    }
}

Sample Payload - Last Seen Calculation

Input Parameters:

Parameter	Type	Description
status	UserStatus	User’s current status. Example: `.offline`
lastActiveAt	Double	Unix timestamp of last activity. Example: `1772110483.0`

Calculation Variables:

Variable	Type	Description
lastActiveDate	Date	Converted Date object from timestamp. Example: `Date(timeIntervalSince1970: 1772110483.0)`
timeAgo	TimeInterval	Seconds since last activity. Example: `3600.0` (1 hour)
minutes	Int	Minutes since last activity. Example: `60`
hours	Int	Hours since last activity. Example: `1`
days	Int	Days since last activity. Example: `0`

Output Examples:

timeAgo (seconds)	Output
300	”Last seen 5 minute(s) ago”
3600	”Last seen 1 hour(s) ago”
86400	”Last seen 1 day(s) ago”
172800	”Last seen 2 day(s) ago”

UserStatus Enum

Value	Raw Value	Description
.online	0	User is currently online and available
.offline	1	User is offline, use `lastActiveAt` for “last seen”

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Login first using `CometChat.login()`
ERR_UID_NOT_FOUND	User with specified UID does not exist	Verify the UID is correct
ERR_INVALID_LIMIT	Invalid limit value provided	Use a limit between 1-100

​Real-time Presence

​Presence Subscription

​AppSettingsBuilder Subscription Methods

​Subscribe to Friends Only

​Subscribe to Specific Roles

​CometChatUserDelegate

​Delegate Methods

​Start Listening for Presence

​Stop Listening for Presence

​Check User Status

​Get Online Users

​Get Offline Users

​User List Presence

​Calculating “Last Seen”

​UserStatus Enum

​Common Error Codes

Real-time Presence

Presence Subscription

AppSettingsBuilder Subscription Methods

Subscribe to Friends Only

Subscribe to Specific Roles

CometChatUserDelegate

Delegate Methods

Start Listening for Presence

Stop Listening for Presence

Check User Status

Get Online Users

Get Offline Users

User List Presence

Calculating “Last Seen”

UserStatus Enum

Common Error Codes