User Management

Create, update, and manage users in your CometChat application

Quick Reference for AI Agents & Developers

// Create user (requires Auth Key - use on backend only)
const user = new CometChat.User("user_uid");
user.setName("John Doe");
user.setAvatar("https://example.com/avatar.png");
user.setRole("premium");
user.setMetadata({ department: "Engineering" });
await CometChat.createUser(user, authKey);

// Update any user (requires Auth Key)
await CometChat.updateUser(user, authKey);

// Update current logged-in user (no Auth Key needed)
await CometChat.updateCurrentUserDetails(user);

// Get user properties
const user = await CometChat.getUser("user_uid");
user.getUid(), user.getName(), user.getAvatar(), user.getStatus()

// Delete user: REST API only (security)

User management is the foundation of your chat application. Before users can send messages, they need to exist in CometChat.

Availability: SDK (with Auth Key), REST API

For production apps, user creation should happen on your backend using the REST API. SDK methods are useful for development and prototyping.

---

User Lifecycle

1. User Registers

   Save user details to your database

2. Create in CometChat

   Create a corresponding CometChat user (via API or SDK)

3. User Logs In

   Authenticate with CometChat using login

4. User Chats

   User can now send and receive messages

---

Create a User

Creating users requires the Auth Key. In production, this should only be done from your backend server. Never expose your Auth Key in client-side code.

JavaScript

const authKey = "YOUR_AUTH_KEY";
const uid = "user1";
const name = "Kevin";

const user = new CometChat.User(uid);
user.setName(name);

CometChat.createUser(user, authKey).then(
  (user) => console.log("User created:", user),
  (error) => console.log("Failed to create user:", error)
);

TypeScript

const authKey: string = "YOUR_AUTH_KEY";
const uid: string = "user1";
const name: string = "Kevin";

const 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("Failed:", error)
);

Async/Await

const createUser = async () => {
  try {
    const authKey = "YOUR_AUTH_KEY";
    const uid = "user1";
    const name = "Kevin";

    const user = new CometChat.User(uid);
    user.setName(name);

    const createdUser = await CometChat.createUser(user, authKey);
    console.log("User created:", createdUser);
  } catch (error) {
    console.log("Failed to create user:", error);
  }
};

With All Properties

JavaScript

const authKey = "YOUR_AUTH_KEY";

const user = new CometChat.User("user1");
user.setName("Kevin Smith");
user.setAvatar("https://example.com/avatar.png");
user.setLink("https://example.com/profile/kevin");
user.setRole("premium");
user.setMetadata({ department: "Engineering", level: 5 });
user.setStatusMessage("Available for chat");
user.setTags(["developer", "team-alpha"]);

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

Async/Await

async function createUserWithAllProperties() {
  try {
    const authKey = "YOUR_AUTH_KEY";

    const user = new CometChat.User("user1");
    user.setName("Kevin Smith");
    user.setAvatar("https://example.com/avatar.png");
    user.setLink("https://example.com/profile/kevin");
    user.setRole("premium");
    user.setMetadata({ department: "Engineering", level: 5 });
    user.setStatusMessage("Available for chat");
    user.setTags(["developer", "team-alpha"]);

    const createdUser = await CometChat.createUser(user, authKey);
    console.log("User created:", createdUser);
    return createdUser;
  } catch (error) {
    console.log("Failed:", error);
    throw error;
  }
}

UID Requirements: Alphanumeric characters, underscores, and hyphens only. No spaces, punctuation, or special characters.

---

Update a User

Update any user’s profile using the Auth Key:

JavaScript

const authKey = "YOUR_AUTH_KEY";
const uid = "user1";

const user = new CometChat.User(uid);
user.setName("Kevin Fernandez");
user.setAvatar("https://example.com/new-avatar.png");

CometChat.updateUser(user, authKey).then(
  (user) => console.log("User updated:", user),
  (error) => console.log("Failed to update:", error)
);

TypeScript

const authKey: string = "YOUR_AUTH_KEY";
const uid: string = "user1";

const user: CometChat.User = new CometChat.User(uid);
user.setName("Kevin Fernandez");
user.setAvatar("https://example.com/new-avatar.png");

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

Async/Await

const updateUser = async () => {
  try {
    const authKey = "YOUR_AUTH_KEY";
    const uid = "user1";

    const user = new CometChat.User(uid);
    user.setName("Kevin Fernandez");
    user.setAvatar("https://example.com/new-avatar.png");

    const updatedUser = await CometChat.updateUser(user, authKey);
    console.log("User updated:", updatedUser);
  } catch (error) {
    console.log("Failed to update:", error);
  }
};

---

Update Current User

The logged-in user can update their own profile without the Auth Key:

JavaScript

const user = new CometChat.User("user1");
user.setName("Kevin Fernandez");
user.setAvatar("https://example.com/new-avatar.png");
user.setStatusMessage("In a meeting");

CometChat.updateCurrentUserDetails(user).then(
  (user) => console.log("Profile updated:", user),
  (error) => console.log("Failed to update:", error)
);

TypeScript

const user: CometChat.User = new CometChat.User("user1");
user.setName("Kevin Fernandez");
user.setAvatar("https://example.com/new-avatar.png");
user.setStatusMessage("In a meeting");

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

Async/Await

const updateMyProfile = async () => {
  try {
    const user = new CometChat.User("user1");
    user.setName("Kevin Fernandez");
    user.setAvatar("https://example.com/new-avatar.png");
    user.setStatusMessage("In a meeting");

    const updatedUser = await CometChat.updateCurrentUserDetails(user);
    console.log("Profile updated:", updatedUser);
  } catch (error) {
    console.log("Failed to update:", error);
  }
};

updateCurrentUserDetails() only updates the logged-in user regardless of the UID provided. You cannot change the user’s role with this method.

---

Delete a User

User deletion is only available via the REST API for security reasons.

curl -X DELETE "https://api-{region}.cometchat.io/v3/users/{uid}" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

View REST API Documentation →

---

User Properties Reference

Property	Editable	Type	Description
uid	Create only	String	Unique identifier
name	Yes	String	Display name
avatar	Yes	String	URL to profile picture
link	Yes	String	URL to profile page
role	Yes*	String	Role for access control
metadata	Yes	Object	Custom JSON data
status	No	String	Online/offline (system managed)
statusMessage	Yes	String	Custom status message
lastActiveAt	No	Number	Unix timestamp of last activity
hasBlockedMe	No	Boolean	If user has blocked logged-in user
blockedByMe	No	Boolean	If logged-in user has blocked this user
tags	Yes	Array	Tags for categorization

*Role can only be updated via updateUser() with Auth Key, not via updateCurrentUserDetails().

---

Working with User Properties

Set Custom Metadata

const user = new CometChat.User("user1");
user.setMetadata({
  department: "Engineering",
  skills: ["JavaScript", "React", "Node.js"],
  preferences: { notifications: true, theme: "dark" }
});

Set User Tags

const user = new CometChat.User("user1");
user.setTags(["premium", "developer", "team-alpha"]);

Get User Properties

const user = await CometChat.getUser("user1");

console.log("UID:", user.getUid());
console.log("Name:", user.getName());
console.log("Avatar:", user.getAvatar());
console.log("Status:", user.getStatus());
console.log("Last Active:", user.getLastActiveAt());
console.log("Metadata:", user.getMetadata());
console.log("Tags:", user.getTags());

---

Best Practices

UID Strategy

• Use your existing user IDs as CometChat UIDs for easy mapping
• Keep UIDs consistent across your system
• Avoid using email addresses as UIDs (they may change)

Security

• Create users from your backend, not client-side
• Use Auth Tokens instead of Auth Key for login in production
• Never expose your Auth Key in client code

User Data Sync

• Keep CometChat user data in sync with your database
• Update CometChat when users change their profile in your app
• Use metadata for app-specific data that doesn’t fit standard fields

---

Next Steps

Retrieve Users

Fetch and search users in your app

Block Users

Block and unblock users

User Presence

Track online/offline status

Authentication

Login and logout users