Overview - CometChat Docs

A Group is a shared conversation space where multiple users can exchange messages and make calls. Groups are identified by a unique guid that you assign during creation and cannot change afterward. CometChat supports three group types:

Type	Visibility	Join behavior
`public`	Listed and searchable	Any user can join without approval
`private`	Hidden from group listings	Users must be added by an admin
`password`	Listed and searchable	Users must provide the correct password to join

If no type is specified during creation, the group defaults to public.

Key behaviors

A group can hold up to 100,000 members. Groups with 300 or fewer members support all features including delivery/read receipts, typing indicators, and unread message counts. Above 300 members, these features are disabled for performance.
GUIDs are automatically converted to lowercase during creation.
A user can be a member of up to 2,000 groups.
Up to 25 members can be added in a single Create Group call via the members object.

How groups connect to other resources

Group Members — Users join groups with a scope (admin, moderator, or participant). Manage membership via the Group Members API.
Messages — Users send and receive Messages within a group conversation.
Banned Users — Admins and moderators can ban members from a group, preventing them from rejoining until unbanned.
Roles & RBAC — A user’s Role controls app-wide permissions, while their group scope controls in-group permissions. See RBAC & SBAC.
Conversations — Each group has a corresponding Conversation that tracks the last message and unread count.

Available operations

Operation	Method	Endpoint	Description
List	`GET`	`/groups`	Retrieve a paginated list of groups
Create	`POST`	`/groups`	Create a new group
Get	`GET`	`/groups/{guid}`	Retrieve a specific group’s details
Update	`PUT`	`/groups/{guid}`	Modify a group’s name, icon, type, or metadata
Delete	`DELETE`	`/groups/{guid}`	Permanently delete a group

Group properties

Property	Type	Description
guid	string	Required. Group’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 for the group. Max 100 characters. Supports all languages and emojis (UTF8mb4).
type	string	Group type: `public`, `private`, or `password`. Defaults to `public` if not specified.
password	string	Password for joining a password-protected group. Only applicable when `type` is `password`.
icon	string	URL to the group’s icon image. Max 3,000 characters. CometChat stores the URL, not the image itself.
description	string	Brief description of the group. Max 255 characters (UTF8mb4).
owner	string	UID of the group owner. If not specified during creation, the system user is assigned as owner.
metadata	object	JSON object for storing additional group information. Max 5 KB.
tags	array of strings	Tags for categorizing and filtering groups. Max 25 tags per group, 100 characters each (UTF8mb4).
members	object	Used during creation to add initial members. Accepts `admins`, `moderators`, `participants`, and `usersToBan` arrays (max 25 users total across all scopes). If a UID appears in multiple arrays, the highest scope applies in the order: admin > moderator > participant. Individual member failures do not cause the create request to fail.
membersCount	integer	Number of members in the group. Read-only.
conversationId	string	Conversation ID associated with this group. Read-only.
createdAt	integer	UNIX timestamp indicating when the group was created. Read-only.

Error handling

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 for this operation
`ERR_GUID_NOT_FOUND`	The specified GUID does not exist
`ERR_GUID_ALREADY_EXISTS`	A group with this GUID already exists
`ERR_PLAN_QUOTA_RESTRICTION`	The group has reached the maximum member limit (100,000)

For the complete list of error codes, see Error Guide. For all system limits (member caps, metadata size, tag counts, etc.), see Properties and Constraints.

​Key behaviors

​How groups connect to other resources

​Available operations

​Group properties

​Error handling

Key behaviors

How groups connect to other resources

Available operations

Group properties

Error handling