Users

Overview of CometChat iOS SDK user management including creating, retrieving, updating, and blocking users with real-time presence tracking.

Quick Reference for AI Agents & Developers

• Create user: CometChat.createUser(user:apiKey:onSuccess:onError:)
• Get user: CometChat.getUser(UID:onSuccess:onError:)
• List users: UsersRequest.UsersRequestBuilder().build() → usersRequest.fetchNext(onSuccess:onError:)
• Block/unblock: CometChat.blockUsers(_:onSuccess:onError:), CometChat.unblockUsers(_:onSuccess:onError:)
• Related: User Management · Retrieve Users · Block Users

The primary aim for our users’ functionality is to allow you to quickly retrieve and add users to CometChat.

You can begin with user management to sync your users to CometChat. Once that is done, you can retrieve users and display them in your app.

---

User Data Model

The User class represents a CometChat user with all their profile information.

Creating a User Object

Swift

// Basic user creation
let user = User(uid: "user123", name: "John Doe")

// Set optional properties
user.avatar = "https://example.com/avatar.png"
user.link = "https://example.com/profile/user123"
user.role = "default"
user.metadata = ["department": "engineering", "level": 5]
user.tags = ["premium", "verified"]

User Properties

Parameter	Type	Editable	Description
uid	String?	No*	Unique user identifier. Must be alphanumeric with underscore/hyphen only. Required for user creation.
name	String?	Yes	Display name of the user. Required for user creation.
avatar	String?	Yes	URL to the user’s avatar/profile image.
link	String?	Yes	URL to the user’s profile page or external link.
role	String?	Yes	Role assigned to the user for role-based access control.
metadata	[String: Any]?	Yes	Custom metadata dictionary for storing additional user information.
status	UserStatus	No	Current online status of the user: .online or .offline.
statusMessage	String?	Yes	Custom status message set by the user.
lastActiveAt	Double	No	Unix timestamp of the user’s last activity.
hasBlockedMe	Bool	No	Indicates if this user has blocked the logged-in user.
blockedByMe	Bool	No	Indicates if the logged-in user has blocked this user.
deactivatedAt	Double	No	Unix timestamp when user was deactivated. Value is 0.0 if user is active.
tags	[String]	Yes	Array of tags for categorizing and filtering users.

* uid is specified on user creation and not editable after that

Sample Payload - User Object

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: "https://example.com/profile/user123"
role	String?	Role assigned to the user for access control. Example: "default"
status	UserStatus	Current online status of the user. Example: .online
statusMessage	String?	Custom status message set by the user. Example: "Available"
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: ["premium", "verified"]
metadata	[String: Any]?	Custom metadata dictionary for additional user info. Example: ["department": "engineering", "level": 5]
metadata.department	String	Department the user belongs to (nested in metadata). Example: "engineering"
metadata.level	Int	User’s level or rank (nested in metadata). Example: 5

UserStatus Enum

Value	Raw Value	Description
.online	0	User is currently online and active in the application.
.offline	1	User is currently offline or not connected.

UID Requirements

Rule	Description
Alphanumeric	Letters (a-z, A-Z) and numbers (0-9) are allowed
Underscore	Underscore character _ is allowed
Hyphen	Hyphen character - is allowed
Spaces	Spaces are NOT allowed in UID
Punctuation	Punctuation marks (., !, ?, etc.) are NOT allowed
Special characters	Special characters (@, #, $, %, etc.) are NOT allowed

Common Error Codes

Error Code	Description	Resolution
ERR_UID_NOT_FOUND	User with specified UID does not exist in CometChat	Verify the UID is correct and the user has been created
ERR_USER_DEACTIVATED	User account has been deactivated	Contact admin to reactivate the user account
ERR_NOT_LOGGED_IN	No user is currently logged in to CometChat	Call CometChat.login() before performing this operation
ERR_UID_ALREADY_EXISTS	User with specified UID already exists	Use a different unique UID for the new user
ERR_INVALID_API_KEY	The provided API key is invalid or expired	Verify API key from CometChat Dashboard
ERR_INVALID_UID	UID contains invalid characters	Use only alphanumeric characters, underscore, and hyphen
ERR_EMPTY_UID	UID is empty or null	Provide a valid non-empty UID
ERR_EMPTY_NAME	Name is empty or null	Provide a valid non-empty name
ERR_INVALID_LIMIT	Invalid limit value provided for pagination	Use a limit value between 1 and 100