Groups

  1. Groups help your users to converse together in a single space. You can have three types of groups - private, public, and password protected.
  2. A maximum of 100000 users can be added to a single group. The following error code would be provided ERR_PLAN_QUOTA_RESTRICTION if you're trying to add members greater than the limit.
  3. They support typing indicators, unread count, transient messages and read receipts.
  4. However, once the size of the group exceeds 300, the conversations and unread message counts are not updated.

📘

GUIDs would be automatically converted to lowercase while creating a group.

The following table lists the properties that the Group API supports.

ParametersTypeDescription
guidstring(mandatory) Specifies group's unique ID. Maximum length is 100 characters.

Allowed characters: alpha-dash (a-z, 0-9 with -and _ ) without spaces
name string(mandatory) Specifies the group's name.
Maximum length is 100 characters.

It also supports emojis.
typestring(optional) Specifies the type of the group.

Allowed types are:
public
private
password

If type is not passed, then by default public type is assigned.
passwordstring(optional) Specifies the password required for a group.
Only required incase of password protected group.
iconstring(optional) Specifies the icon of the group.
If left empty, no group icon is set for the group.

CometChat doesn’t save the image on its servers.. There is no limit on the image resolution. It depends on the implementation.

Maximum length is 3000 characters.
descriptionstring(optional) Specifies the group description.

Maximum length is 255 characters.
ownerstring(optional) Specifies the owner of the group.
If passed with the UID of an existing user, the User would be made the owner of the group.

If not passed, the system user would be considered the owner of the group.
metadata nested object(optional) Specifies a JSON object to store up to 1.6K characters (JSON stringified metadata) for additional user information.
tags array of strings(optional) Specifies a list of tags to be associated with certain groups.

A maximum of 25 tags can be associated with a single group.
membersobject(optional) The members object allows adding members with the allowed member scopes and banning users.

It can have the below optional properties:

admins: A string array of UIDs of the existing users to be added as group admins.
moderators: A string array of UIDs of the existing users to be added as group moderators.
participants: A string array of UIDs of the existing users to be added as group participants.
usersToBan: A string array of UIDs of the existing users to be added as group participants.

Failure to adding a member or banning a user does not result into create group API failure.
However, the individual member failure can be seen in the error objects in members.

If the same UID is added to more than one members array then the scope UID will get the scopes in the order below admin, moderator, participant.
For example, if the UID superhero1 is part of admins, moderators and usersToBan arrays then it will appear in the only members.admins property in the response.

A maximum of 25 users can be added across all the scopes of member objects.
membersCountintegerSpecifies the number of members in the group.
createdAtintegerUNIX Timestamp specifies the time when the user was created.
conversationIdstringSpecifies the conversation ID of the group.

The following table lists the most common error codes the Group API may return in case of an error:

CodeDescription
ERR_GUID_NOT_FOUNDIndicates that the GUID does not exist.
ERR_EMPTY_GROUP_PASSIndicates one from the below:

1. Empty password for password type group to create group API.
2. Empty password for pasword type group to join group API.
ERR_GROUP_DELETE_FAILEDIndicates that the API failed to delete the group.
ERR_NOT_A_MEMBERIndicates that the user is not a member of the group.
ERR_WRONG_GROUP_PASSIndicates password mismatch for the password type group.
ERR_ALREADY_JOINEDIndicates that the user has already joined the group.
ERR_GROUP_NOT_JOINEDIndicates that the user is trying to access the group feature without joining it.
ERR_GROUP_JOIN_NOT_ALLOWEDIndicates that the user is trying to join the private group.
ERR_MEMBER_DELETE_FAILEDIndicates that the API has failed to remove a user from the group.
ERR_NO_VACANCYIndicates that the group is full.
ERR_SAME_SCOPEIndicates that the existing and new scope are same.
ERR_MEMBER_SCOPE_CHANGE_FAILEDIndicates that the has failed to change the scope.
ERR_NOT_A_BANNED_USERIndicates that the API is trying to unban non-banned users.
ERR_BANNED_GROUPMEMBERIndicates that the banned user is trying to access the group features.
ERR_ALREADY_BANNEDThis indicates that the API is trying to ban an already banned user.
ERR_MEMBER_BAN_FAILEDIndicates that the API has failed to ban a user from the group.
ERR_MEMBER_UNBAN_FAILEDIndicates that the API has failed to unban a user for the group.
ERR_GROUP_NO_CLEARANCEIndicates that the user does not have permission to perform the action in the group. For example, users with participant scope can not kick users with admin or moderator scope.
ERR_GROUP_NO_ADMIN_SCOPEIndicates that the user does not have admin scope in the group.
ERR_GROUP_NO_MODERATOR_SCOPEIndicates that the user does not have moderator scope in the group.
ERR_GROUP_NO_SCOPE_CLEARANCEIndicates that the user does not have permission to change the scope of other user.
ERR_GROUP_NO_SELF_ACTIONIndicates that the user is not allowed to perform an action on himself. For example, changing his own scope.