User Management

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

Quick Reference for AI Agents & Developers

// Create a user
const user = new CometChat.User("user1");
user.setName("Kevin");
await CometChat.createUser(user, "AUTH_KEY");

// Update a user
user.setName("Kevin Fernandez");
await CometChat.updateUser(user, "AUTH_KEY");

// Update logged-in user (no auth key needed)
await CometChat.updateCurrentUserDetails(user);

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

When a user logs into your app, you need to programmatically login the user into CometChat. But before you log in the user to CometChat, you need to create the user.

Available via: SDK | REST API | UI Kits

Summing up-

When a user registers in your app

1. You add the user details in your database
2. You create a user in CometChat

When a user logs into your app

1. You log in the user to your app
2. You log in the user in CometChat (programmatically)

Creating a user

Ideally, user creation should take place at your backend. You can refer our Rest API to learn more about creating a user and use the appropriate code sample based on your backend language.

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.

However, if you wish to create users on the fly, you can use the createUser() method. This method takes a User object and the Auth Key as input parameters and returns the created User object if the request is successful.

JavaScript

let authKey = "AUTH_KEY";
var uid = "user1";
var name = "Kevin";

var user = new CometChat.User(uid);

user.setName(name);

CometChat.createUser(user, authKey).then(
  user => {
    console.log("user created", user);
  }, error => {
    console.log("error", error);
  }
)

TypeScript

let authKey: string = "AUTH_KEY";
var uid: string = "user1";
var name: string = "Kevin";

var user: CometChat.User = new CometChat.User(uid);

user.setName(name);

CometChat.createUser(user, authKey).then(
  (user: CometChat.User) => {
    console.log("user created", user);
  }, (error: CometChat.CometChatException) => {
    console.log("error", error);
  }
);

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

Updating a user

Updating a user similar to creating a user should ideally be achieved at your backend using the Restful APIs. For more information, you can check the update a user section. However, this can be achieved on the fly as well as using the updateUser() method. This method takes a User object and the Auth Key as inputs and returns the updated User object on the successful execution of the request.

JavaScript

let authKey = "AUTH_KEY";
let uid = "user1";
let name = "Kevin Fernandez";

var user = new CometChat.User(uid);

user.setName(name);

CometChat.updateUser(user, authKey).then(
  user => {
    console.log("user updated", user);
  }, error => {
    console.log("error", error);
  }
)

TypeScript

let authKey: string = "AUTH_KEY";
var uid: string = "user1";
var name: string = "Kevin Fernandez";

var user: CometChat.User = new CometChat.User(uid);

user.setName(name);

CometChat.updateUser(user, authKey).then(
  (user: CometChat.User) => {
    console.log("user updated", user);
  }, (error: CometChat.CometChatException) => {
    console.log("error", error);
  }
)

Please make sure the User object provided to the updateUser() method has the UID of the user to be updated set.

Updating logged-in user

Updating a logged-in user is similar to updating a user. The only difference being this method does not require an AuthKey. This method takes a User object as input and returns the updated User object on the successful execution of the request.

JavaScript

let uid = "user1";
let name = "Kevin Fernandez";

var user = new CometChat.User(uid);

user.setName(name);

CometChat.updateCurrentUserDetails(user).then(
  user => {
    console.log("user updated", user);
  }, error => {
    console.log("error", error);
  }
)

TypeScript

var uid: string = "user1";
var name: string = "Kevin Fernandez";

var user: CometChat.User = new CometChat.User(uid);

user.setName(name);

CometChat.updateCurrentUserDetails(user).then(
  (user: CometChat.User) => {
    console.log("user updated", user);
  }, (error: CometChat.CometChatException) => {
    console.log("error", error);
  }
);

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

Deleting a user can only be achieved via the Restful APIs. For more information please check the delete a user section.

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

Best Practices

Practice	Details
Backend user creation	Always create and update users from your backend server using the REST API to keep your Auth Key secure
UID format	Use alphanumeric characters, underscores, and hyphens only. Avoid spaces and special characters
Metadata usage	Store additional user info (e.g., department, preferences) in the metadata JSON field rather than creating custom fields
Sync on registration	Create the CometChat user immediately when a user registers in your app to avoid login failures

Troubleshooting

Symptom	Cause	Fix
createUser() fails with “Auth Key not found”	Invalid or missing Auth Key	Verify the Auth Key from your CometChat Dashboard
createUser() fails with “UID already exists”	A user with that UID was already created	Use updateUser() instead, or choose a different UID
updateCurrentUserDetails() doesn’t update role	Role cannot be changed for the logged-in user	Use updateUser() with Auth Key from your backend to change roles
User not appearing in user list	User was created but not yet indexed	Wait a moment and retry. Ensure createUser() resolved successfully

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.