Create

Create a CometChat user role with REST API to define permissions for app users and role-based feature access.

POST /roles

Create

cURL

curl --request POST \
  --url https://{appId}.api-{region}.cometchat.io/v3/roles \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "role": "",
  "name": "",
  "description": "",
  "metadata": {},
  "settings": {}
}
'

import requests

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

payload = {
    "role": "",
    "name": "",
    "description": "",
    "metadata": {},
    "settings": {}
}
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({role: '', name: '', description: '', metadata: {}, settings: {}})
};

fetch('https://{appId}.api-{region}.cometchat.io/v3/roles', 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/roles",
  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([
    'role' => '',
    'name' => '',
    'description' => '',
    'metadata' => [
        
    ],
    'settings' => [
        
    ]
  ]),
  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/roles"

	payload := strings.NewReader("{\n  \"role\": \"\",\n  \"name\": \"\",\n  \"description\": \"\",\n  \"metadata\": {},\n  \"settings\": {}\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/roles")
  .header("apikey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"role\": \"\",\n  \"name\": \"\",\n  \"description\": \"\",\n  \"metadata\": {},\n  \"settings\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"role\": \"\",\n  \"name\": \"\",\n  \"description\": \"\",\n  \"metadata\": {},\n  \"settings\": {}\n}"

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

200

{
  "data": {
    "role": "manager",
    "name": "manager",
    "description": "This role gives an update access",
    "metadata": {
      "email": "[e-mail]"
    },
    "settings": {
      "listUsers": "all",
      "sendMessagesTo": "friendsOnly"
    },
    "createdAt": 1638343994
  }
}

Constraints

Item	Constraint	Notes
Role UID	100 characters, alpha-dash (a-z, 0-9, -, _)	CometChat forces the UID to lowercase
Role name	100 characters (UTF8mb4)	Supports all languages and emojis
Role description	255 characters (UTF8mb4)	Describe the role’s purpose and permissions
Metadata	No limit	Store additional role configuration as JSON key-value pairs

Authorizations

apikey · string · header · required

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

Body

application/json

role · string · default: "" · required

A unique identifier for the role.

name · string · default: "" · required

Friendly name of the role.

description · string · default: ""

Description of the role.

metadata · object

Addition information about the role as JSON.

settings · object

Role settings that is used for restricting list users/send message. Possible values for listUsers & sendMessagesTo are all and friendsOnly

Response

200 - application/json

Created a new Role

data · object