Overview

Create and manage groups for multi-user conversations — public, private, or password-protected.

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.