Overview

Manage users in your CometChat app — create, retrieve, update, and delete user accounts that power messaging and calling.

A User is the core identity in CometChat. Every person (or bot) that sends messages, joins groups, or makes calls must exist as a User. Users are identified by a unique uid that you assign during creation and cannot change afterward.

How Users connect to other resources

• Auth Tokens — A User needs an auth token to log in via the SDK. You can generate one during creation (withAuthToken: true) or separately via the Auth Tokens API.
• Groups — Users can join up to 2,000 Groups and participate in group messaging and calling.
• Messages — Users send and receive Messages in 1-on-1 or group conversations.
• Friends — Users can add up to 1,000 Friends. Friendships are bidirectional.
• Roles — Users can be assigned a Role that controls permissions. If no role is set, the default role applies.
• Blocked Users — Users can block other users to prevent all direct communication in both directions.

Common workflow

1. Create a User with withAuthToken: true to get an auth token in the same call.
2. Use the auth token to initialize the CometChat SDK on the client.
3. The user can now send messages, join groups, and make calls.

UIDs are automatically converted to lowercase during creation. For example, CometChat-UID-1 becomes cometchat-uid-1.

Available operations

Operation	Method	Endpoint	Description
List	GET	/users	Retrieve a paginated list of users with filtering options
Create	POST	/users	Create a new user in your app
Get	GET	/users/{uid}	Retrieve a specific user’s details
Update	PUT	/users/{uid}	Modify a user’s profile (name, avatar, role, metadata)
Delete	DELETE	/users/{uid}	Deactivate or permanently delete a user
Deactivate	DELETE	/users	Temporarily disable users while preserving their data
Reactivate	PUT	/users	Restore previously deactivated users

User properties

The following table lists the properties that the User object supports.

Property	Type	Description
uid	string	Required. User’s unique identifier. Max 100 characters. Alphanumeric with dashes and underscores only, no spaces. Case-insensitive and immutable after creation.
name	string	Required. Display name shown in chat interfaces and notifications. Max 100 characters. Supports all languages and emojis (UTF8mb4).
avatar	string	URL to the user’s profile picture. Max 3,000 characters. CometChat stores the URL, not the image itself. Recommended size: 200×200 pixels.
link	string	URL to the user’s profile page in your application. Max 3,000 characters.
role	string	Role assigned to the user. Must be created beforehand using the Create Role API. Defaults to the default role if not set.
metadata	object	JSON object for storing additional user information (e.g., email, phone, preferences). Max 5 KB. Use the @private key for sensitive data that should only be visible to the user themselves and via admin APIs.
tags	array of strings	Tags for categorizing and filtering users. Max 25 tags per user, 100 characters each (UTF8mb4). Useful for segmenting by department, location, or custom criteria.
withAuthToken	boolean	When true on creation, includes the auth token in the response — saving a separate API call. Only applicable during Create.
createdAt	integer	UNIX timestamp indicating when the user was created. System-generated, read-only.

Error handling

When API calls fail, CometChat returns structured error responses. The most common errors for User operations:

Error Code	Description
AUTH_ERR_EMPTY_APIKEY	API key is missing from the request headers
AUTH_ERR_APIKEY_NOT_FOUND	The provided API key is invalid
AUTH_ERR_NO_ACCESS	The API key doesn’t have the required scope (e.g., using an authOnly key for a fullAccess operation)
ERR_UID_NOT_FOUND	The specified UID does not exist, or the user has been deactivated

For the complete list of error codes, see Error Guide.

For all system limits (metadata size, tag counts, ID length, etc.), see Properties and Constraints.