Create

Create a CometChat user with REST API by setting UID, name, avatar, role, metadata, and other profile fields.

POST /users

Create

cURL

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": "[e-mail]",
      "contactNumber": "0123456789"
    }
  },
  "tags": [],
  "withAuthToken": true
}
'

import requests

url = "https://{appId}.api-{region}.cometchat.io/v3/users"

payload = {
    "uid": "<string>",
    "name": "<string>",
    "avatar": "<string>",
    "link": "<string>",
    "role": "<string>",
    "statusMessage": "<string>",
    "metadata": { "@private": {
            "email": "[e-mail]",
            "contactNumber": "0123456789"
        } },
    "tags": [],
    "withAuthToken": True
}
headers = {
    "apikey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    uid: '<string>',
    name: '<string>',
    avatar: '<string>',
    link: '<string>',
    role: '<string>',
    statusMessage: '<string>',
    metadata: {'@private': {email: '[e-mail]', contactNumber: '0123456789'}},
    tags: [],
    withAuthToken: true
  })
};

fetch('https://{appId}.api-{region}.cometchat.io/v3/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{appId}.api-{region}.cometchat.io/v3/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'uid' => '<string>',
    'name' => '<string>',
    'avatar' => '<string>',
    'link' => '<string>',
    'role' => '<string>',
    'statusMessage' => '<string>',
    'metadata' => [
        '@private' => [
                'email' => '[e-mail]',
                'contactNumber' => '0123456789'
        ]
    ],
    'tags' => [
        
    ],
    'withAuthToken' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{appId}.api-{region}.cometchat.io/v3/users"

	payload := strings.NewReader("{\n  \"uid\": \"<string>\",\n  \"name\": \"<string>\",\n  \"avatar\": \"<string>\",\n  \"link\": \"<string>\",\n  \"role\": \"<string>\",\n  \"statusMessage\": \"<string>\",\n  \"metadata\": {\n    \"@private\": {\n      \"email\": \"[e-mail]\",\n      \"contactNumber\": \"0123456789\"\n    }\n  },\n  \"tags\": [],\n  \"withAuthToken\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{appId}.api-{region}.cometchat.io/v3/users")
  .header("apikey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"uid\": \"<string>\",\n  \"name\": \"<string>\",\n  \"avatar\": \"<string>\",\n  \"link\": \"<string>\",\n  \"role\": \"<string>\",\n  \"statusMessage\": \"<string>\",\n  \"metadata\": {\n    \"@private\": {\n      \"email\": \"[e-mail]\",\n      \"contactNumber\": \"0123456789\"\n    }\n  },\n  \"tags\": [],\n  \"withAuthToken\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{appId}.api-{region}.cometchat.io/v3/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apikey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"uid\": \"<string>\",\n  \"name\": \"<string>\",\n  \"avatar\": \"<string>\",\n  \"link\": \"<string>\",\n  \"role\": \"<string>\",\n  \"statusMessage\": \"<string>\",\n  \"metadata\": {\n    \"@private\": {\n      \"email\": \"[e-mail]\",\n      \"contactNumber\": \"0123456789\"\n    }\n  },\n  \"tags\": [],\n  \"withAuthToken\": true\n}"

response = http.request(request)
puts response.read_body

200

{
  "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"
  }
}

Constraints

Item	Constraint	Notes
UID character limit	100 characters	Alphanumeric with dashes only; spaces not allowed
User name	100 characters (UTF8mb4)	Supports all languages and emojis
Avatar URL	3000 characters max	CometChat doesn’t store the image; no resolution limit
Profile URL	3000 characters max	Same as avatar
Metadata	5 KB max (within 10 KB POST limit)	Store custom key-value pairs
Tags	Up to 25 tags, 100 characters each (UTF8mb4)	Enable filtering and searching
Maximum groups per user	2000	Must leave existing groups to join new ones beyond limit
Maximum friends per user	1000	Bidirectional relationships count toward both users’ limits
Maximum auth tokens per user	100 active (rolling retention)	Oldest tokens are archived when limit is exceeded
Maximum Bot users per app	25	Special accounts for automated messaging
Maximum users per app	No limit	Pricing 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 [blocked] or SMS Notification [blocked] extensions, Please add the private metadata here.

Show child attributes

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