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