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
- Create a User with
withAuthToken: true to get an auth token in the same call.
- Use the auth token to initialize the CometChat SDK on the client.
- 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 |
