> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Create and manage CometChat groups with REST APIs for public, private, and password-protected conversations.

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](/rest-api/groups/create) 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](/rest-api/group-members).
* **Messages** — Users send and receive [Messages](/rest-api/messages) within a group conversation.
* **Banned Users** — Admins and moderators can [ban members](/rest-api/banned-users) from a group, preventing them from rejoining until unbanned.
* **Roles & RBAC** — A user's [Role](/rest-api/roles) controls app-wide permissions, while their group scope controls in-group permissions. See [RBAC & SBAC](/rest-api/rbac-overview).
* **Conversations** — Each group has a corresponding [Conversation](/rest-api/conversations) that tracks the last message and unread count.

### Available operations

| Operation | Method | Endpoint | Description |
| - | - | - | - |
| [List](/rest-api/groups/list) | `GET` | `/groups` | Retrieve a paginated list of groups |
| [Create](/rest-api/groups/create) | `POST` | `/groups` | Create a new group |
| [Get](/rest-api/groups/get) | `GET` | `/groups/{guid}` | Retrieve a specific group's details |
| [Update](/rest-api/groups/update) | `PUT` | `/groups/{guid}` | Modify a group's name, icon, type, or metadata |
| [Delete](/rest-api/groups/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](/articles/error-guide).

For all system limits (member caps, metadata size, tag counts, etc.), see [Properties and Constraints](/articles/properties-and-constraints).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.