User Management

Create, update, and manage CometChat users programmatically using the Flutter SDK. Includes user creation, profile updates, and the User class reference.

AI Integration Quick Reference

// Create a user
User user = User(uid: "user1", name: "Kevin");
CometChat.createUser(user, "AUTH_KEY", onSuccess: (User user) {
  debugPrint("User created: ${user.name}");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

// Update a user (requires API Key)
User updatedUser = User(uid: "user1", name: "Kevin Fernandez");
CometChat.updateUser(updatedUser, "AUTH_KEY", onSuccess: (User user) {
  debugPrint("User updated: ${user.name}");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

// Update logged-in user (no auth key needed)
User currentUser = User(name: "New Name");
CometChat.updateCurrentUserDetails(currentUser, onSuccess: (User user) {
  debugPrint("User updated: ${user.name}");
}, onError: (CometChatException e) {
  debugPrint("Error: ${e.message}");
});

Note: User creation/deletion should ideally happen on your backend via the REST API.

Users must exist in CometChat before they can log in. This page covers creating, updating, and deleting users. All methods that return user data return a User object.

The typical flow:

1. User registers in your app → Create user in CometChat
2. User logs into your app → Log user into CometChat

User deletion is only available via the REST API — there is no client-side SDK method for it.

Creating a User

User creation should ideally happen on your backend via the REST API.

Security: Never expose your Auth Key in client-side production code. User creation and updates using Auth Key should ideally happen on your backend server. Use client-side creation only for prototyping or development.

For client-side creation (development only), use createUser():

Dart

String authKey = "AUTH_KEY"; // Replace with the auth key of app
User user = User(uid: "usr1", name: "Kevin"); // Replace with name and uid of user

CometChat.createUser(user, authKey, onSuccess: (User user) {
  debugPrint("Create User successful $user");
}, onError: (CometChatException e) {
  debugPrint("Create User Failed with exception ${e.message}");
});

Parameters

Parameter	Type	Description
user	User	A User object containing the details of the user to be created. The uid and name fields are required.
authKey	String	Your CometChat Auth Key. Use only for development — never expose in production client code.
onSuccess	Function(User user)	Callback triggered on successful user creation, returning the created User object.
onError	Function(CometChatException excep)	Callback triggered on failure, returning a CometChatException with error details.

Returns a User object. See User Class for all available fields.

Response

On Success — A User object containing all details of the created user:

User Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the user	"usr1"
name	string	Display name of the user	"Kevin"
link	string	Profile link	null
avatar	string	Avatar URL	null
metadata	object	Custom metadata	{}
status	string	Online status	"offline"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	List of tags associated with the user	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	0

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_UID_NOT_FOUND"
message	string	Human-readable error message	"The specified UID does not exist."
details	string	Additional technical details	"Please provide a valid UID for the user."

UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed.

Updating a User

Like creation, user updates should ideally happen on your backend via the REST API.

For client-side updates (development only), use updateUser():

Dart

String apiKey = "AUTH_KEY"; // Replace with the auth key of app
User user = User(uid: "usr1", name: "Kevin Fernandez");

CometChat.updateUser(user, apiKey, onSuccess: (User user) {
  debugPrint("User updated: $user");
}, onError: (CometChatException e) {
  debugPrint("Update User Failed with exception ${e.message}");
});

Ensure the User object has the correct UID set.

Parameters

Parameter	Type	Description
user	User	A User object with the uid of the user to update and the fields to change.
apiKey	String	Your CometChat Auth Key. Use only for development — never expose in production client code.
onSuccess	Function(User retUser)	Callback triggered on successful update, returning the updated User object.
onError	Function(CometChatException excep)	Callback triggered on failure, returning a CometChatException with error details.

Returns a User object. See User Class for all available fields.

Response

On Success — A User object containing all details of the updated user:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the user	"usr1"
name	string	Display name of the user	"Kevin Fernandez"
link	string	Profile link	null
avatar	string	Avatar URL	null
metadata	object	Custom metadata	{}
status	string	Online status	"offline"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	List of tags associated with the user	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	0

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_UID_NOT_FOUND"
message	string	Human-readable error message	"The specified UID does not exist."
details	string	Additional technical details	"Please provide a valid UID for the user."

Updating Logged-in User

Use updateCurrentUserDetails() to update the current user without an Auth Key. Note: You cannot update the user’s role with this method.

Dart

User user = User(name: 'Updated Name');

CometChat.updateCurrentUserDetails(user, onSuccess: (User updatedUser) {
  debugPrint("Updated User: $updatedUser");
}, onError: (CometChatException e) {
  debugPrint("Updated User exception : ${e.message}");
});

Parameters

Parameter	Type	Description
user	User	A User object with the fields to update. The uid is ignored — only the logged-in user is updated.
onSuccess	Function(User retUser)	Callback triggered on successful update, returning the updated User object.
onError	Function(CometChatException excep)	Callback triggered on failure, returning a CometChatException with error details.

The method returns a User object.

Response

On Success — A User object containing all details of the updated user:

User Object:

Parameter	Type	Description	Sample Value
uid	string	Unique identifier of the user	"cometchat-uid-1"
name	string	Display name of the user	"Updated Name"
link	string	Profile link	null
avatar	string	Avatar URL	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"
metadata	object	Custom metadata	{}
status	string	Online status	"online"
role	string	User role	"default"
statusMessage	string	Status message	null
tags	array	List of tags associated with the user	[]
hasBlockedMe	boolean	Whether this user has blocked the current user	false
blockedByMe	boolean	Whether the current user has blocked this user	false
lastActiveAt	number	Epoch timestamp of last activity	1745554700

Error

Parameter	Type	Description	Sample Value
code	string	Error code identifier	"ERR_UID_NOT_FOUND"
message	string	Human-readable error message	"The specified UID does not exist."
details	string	Additional technical details	"Please provide a valid UID for the user."

By using the updateCurrentUserDetails() method one can only update the logged-in user irrespective of the UID passed. Also, it is not possible to update the role of a logged-in user.

Deleting a User

User deletion is only available via the REST API.

User Class

Field	Editable	Information
uid	specified on user creation. Not editable after that	Unique identifier of the user
name	Yes	Display name of the user
avatar	Yes	URL to profile picture of the user
link	Yes	URL to profile page
role	Yes	User role of the user for role based access control
metadata	Yes	Additional information about the user as JSON
status	No	Status of the user. Could be either online/offline
statusMessage	Yes	Any custom status message that needs to be set for a user
lastActiveAt	No	The unix timestamp of the time the user was last active.
hasBlockedMe	No	A boolean that determines if the user has blocked the logged in user
blockedByMe	No	A boolean that determines if the logged in user has blocked the user
tags	Yes	A list of tags to identify specific users

Next Steps

Retrieve Users

Fetch and filter user lists with pagination.

User Presence

Monitor real-time online/offline status.

Block Users

Block and unblock users.

Authentication

Log users into CometChat.