User Management - CometChat Docs

Quick Reference - Create and update users:

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

// Update logged-in user
const me = new CometChat.User("user1");
me.setName("Kevin Fernandez");
await CometChat.updateCurrentUserDetails(me);

Available via: SDK | 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. Summing up- When a user registers in your app

You add the user details in your database
You create a user in CometChat

When a user logs into your app

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

Creating a user

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

The Auth Key is intended for development and testing only. In production, create users from your backend using the REST API with your API Key instead.

JavaScript
TypeScript

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);
  }
)

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);
  }
);

Response

On Success — createUser() returns the created User object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the user	`"test_user_1772166127823"`
`name`	string	Display name of the user	`"Test User"`
`role`	string	User’s role	`"default"`
`status`	string	User’s online status	`"offline"`
`hasBlockedMe`	boolean	Whether this user has blocked the current user	`false`
`blockedByMe`	boolean	Whether the current user has blocked this user	`false`
`deactivatedAt`	number	Timestamp when user was deactivated (0 if active)	`0`
`createdAt`	number	Unix timestamp when user was created	`1772166128`

When creating a user with all optional fields set:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the user	`"test_full_1772166127993"`
`name`	string	Display name of the user	`"Full Test User"`
`avatar`	string	URL to user’s avatar image	`"https://example.com/avatar.png"`
`link`	string	URL to user’s profile page	`"https://example.com/profile"`
`role`	string	User’s role	`"default"`
`status`	string	User’s online status	`"offline"`
`statusMessage`	string	Custom status message	`"Hello World"`
`metadata`	object	Custom metadata attached to the user	`{"custom": "data"}`
`tags`	array	Tags associated with the user	`["tag1", "tag2"]`
`hasBlockedMe`	boolean	Whether this user has blocked the current user	`false`
`blockedByMe`	boolean	Whether the current user has blocked this user	`false`
`deactivatedAt`	number	Timestamp when user was deactivated (0 if active)	`0`
`createdAt`	number	Unix timestamp when user was created	`1772166129`

UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed. CometChat automatically converts any uppercase characters in the UID to lowercase.

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
TypeScript

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);
  }
)

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);
  }
)

Response

On Success — updateUser() returns the updated User object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the user	`"test_user_1772167015122"`
`name`	string	Display name of the user	`"Updated Test User"`
`role`	string	User’s role	`"default"`
`status`	string	User’s online status	`"offline"`
`hasBlockedMe`	boolean	Whether this user has blocked the current user	`false`
`blockedByMe`	boolean	Whether the current user has blocked this user	`false`
`deactivatedAt`	number	Timestamp when user was deactivated (0 if active)	`0`
`createdAt`	number	Unix timestamp when user was created	`1772167016`

When updating a user with all optional fields:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the user	`"test_full_1772167015291"`
`name`	string	Display name of the user	`"Updated Full User"`
`avatar`	string	URL to user’s avatar image	`"https://example.com/new-avatar.png"`
`link`	string	URL to user’s profile page	`"https://example.com/new-profile"`
`role`	string	User’s role	`"admin"`
`status`	string	User’s online status	`"offline"`
`statusMessage`	string	Custom status message	`"Updated status"`
`metadata`	object	Custom metadata attached to the user	`{"updated": true}`
`tags`	array	Tags associated with the user	`["updated-tag"]`
`hasBlockedMe`	boolean	Whether this user has blocked the current user	`false`
`blockedByMe`	boolean	Whether the current user has blocked this user	`false`
`deactivatedAt`	number	Timestamp when user was deactivated (0 if active)	`0`
`createdAt`	number	Unix timestamp when user was created	`1772167016`

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
TypeScript

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);
  }
)  

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);
  }
);

Response

On Success — updateCurrentUserDetails() returns the updated User object with additional session data:

Parameter	Type	Description	Sample Value
`uid`	string	Unique identifier of the user	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://artriva.com/media/k2/galleries/20/d.jpg"`
`authToken`	string	Authentication token for the user	`"cometchat-uid-7_177199269018c2c2995f0b69b3844abc9fdb9843"`
`role`	string	User’s role	`"default"`
`status`	string	User’s online status	`"online"`
`statusMessage`	string	Custom status message	`"Testing CometChat SDK"`
`lastActiveAt`	number	Unix timestamp of last activity	`1772163866`
`hasBlockedMe`	boolean	Whether this user has blocked the current user	`false`
`blockedByMe`	boolean	Whether the current user has blocked this user	`false`
`deactivatedAt`	number	Timestamp when user was deactivated (0 if active)	`0`
`tags`	array	Tags associated with the user	`["vip"]`
`wsChannel`	object	WebSocket channel information	`{"identity": "[2748663902141719]cometchat-uid-7"}`
`settings`	object	App settings and feature flags (large object with trial info, extensions, parameters)	See CometChat Dashboard
`jwt`	string	JSON Web Token for API authentication	JWT string

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

Create users from your backend

Use the REST API with your API Key to create users server-side. The createUser() SDK method requires the Auth Key, which should not be exposed in production client apps.

Keep UIDs consistent with your system

Use the same user identifier from your backend as the CometChat UID. This simplifies mapping between your user system and CometChat.

Use updateCurrentUserDetails for self-updates

When the logged-in user updates their own profile, use updateCurrentUserDetails() which doesn’t require an Auth Key. Reserve updateUser() for admin-level operations from your backend.

Troubleshooting

createUser fails with 'UID already exists'

Each UID must be unique across your CometChat app. If the user already exists, use updateUser() instead, or skip creation and proceed to login.

updateCurrentUserDetails doesn't update role

Role updates are not allowed via updateCurrentUserDetails(). Use the REST API or updateUser() with Auth Key to change a user’s role.

UID validation error

UIDs can only contain alphanumeric characters, underscores, and hyphens. Spaces, punctuation, and other special characters are not allowed.

Next Steps

Retrieve Users

Fetch user lists, search users, and get user details

Block Users

Block and unblock users, retrieve blocked user lists

Authentication

Log users into CometChat after creation

User Presence

Track online/offline status of users in real time

​Creating a user

​Updating a user

​Updating logged-in user

​Deleting a user

​User Class

​Best Practices

​Troubleshooting

​Next Steps

Retrieve Users

Block Users

Authentication

User Presence

Creating a user

Updating a user

Updating logged-in user

Deleting a user

User Class

Best Practices

Troubleshooting

Next Steps