Skip to main content
POST
/
users
Create
curl --request POST \
  --url https://{appId}.api-{region}.cometchat.io/v3/users \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "uid": "<string>",
  "name": "<string>",
  "avatar": "<string>",
  "link": "<string>",
  "role": "<string>",
  "statusMessage": "<string>",
  "metadata": {
    "@private": {
      "email": "user@email.com",
      "contactNumber": "0123456789"
    }
  },
  "tags": [],
  "withAuthToken": true
}
'
{
  "data": {
    "uid": "cometchat-uid-6",
    "name": "Barry Allen",
    "link": "https://cometchat.com",
    "avatar": "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp",
    "metadata": {
      "rawMetadata": "{'gender':'Male'}"
    },
    "status": "offline",
    "role": "manager",
    "createdAt": 1638354015,
    "tags": [
      "Engineer",
      "manager"
    ],
    "authToken": "cometchat-uid-6_16383540156641d37a023c75d26f4c22a21ff126"
  }
}

Documentation Index

Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Constraints

ItemConstraintNotes
UID character limit100 charactersAlphanumeric with dashes only; spaces not allowed
User name100 characters (UTF8mb4)Supports all languages and emojis
Avatar URL3000 characters maxCometChat doesn’t store the image; no resolution limit
Profile URL3000 characters maxSame as avatar
Metadata5 KB max (within 10 KB POST limit)Store custom key-value pairs
TagsUp to 25 tags, 100 characters each (UTF8mb4)Enable filtering and searching
Maximum groups per user2000Must leave existing groups to join new ones beyond limit
Maximum friends per user1000Bidirectional relationships count toward both users’ limits
Maximum auth tokens per user100 active (rolling retention)Oldest tokens are archived when limit is exceeded
Maximum Bot users per app25Special accounts for automated messaging
Maximum users per appNo limitPricing based on Monthly Active Users (MAU)
For the complete error reference, see Error Guide.

Authorizations

​
apikey
string
header
required

API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).

Body

application/json
​
uid
string
required

Unique identifier of the user. Please refer to https://prodocs.cometchat.com/docs/concepts#uid

​
name
string
required

Display name of the user.

​
avatar
string

URL to profile picture of the user.

​
link
string

URL to profile page.

​
role
string

User role of the user for role based access control.

​
statusMessage
string

A message providing context related to the user's current status or mood.

​
metadata
object

Additional information about the user as JSON. If you plan to use Email Notification or SMS Notification extensions, Please add the private metadata here.

​
tags
string[]

A list of tags to identify specific users.

​
withAuthToken
boolean

Includes authToken of created user in response.

Response

200 - application/json

Create User

​
data
object