- Groups help your users to converse together in a single space. You can have three types of groups - private, public, and password protected.
- 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.
- They support typing indicators, unread count, transient messages and read receipts.
- 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.
| Parameters | Type | Description |
|---|---|---|
| guid | string | (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. |
| type | string | (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. |
| password | string | (optional) Specifies the password required for a group. Only required incase of password protected group. |
| icon | string | (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. |
| description | string | (optional) Specifies the group description. Maximum length is 255 characters. |
| owner | string | (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. |
| members | object | (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. |
| membersCount | integer | Specifies the number of members in the group. |
| createdAt | integer | UNIX Timestamp specifies the time when the user was created. |
| conversationId | string | Specifies 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:
| Code | Description |
|---|---|
| ERR_GUID_NOT_FOUND | Indicates that the GUID does not exist. |
| ERR_EMPTY_GROUP_PASS | Indicates 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_FAILED | Indicates that the API failed to delete the group. |
| ERR_NOT_A_MEMBER | Indicates that the user is not a member of the group. |
| ERR_WRONG_GROUP_PASS | Indicates password mismatch for the password type group. |
| ERR_ALREADY_JOINED | Indicates that the user has already joined the group. |
| ERR_GROUP_NOT_JOINED | Indicates that the user is trying to access the group feature without joining it. |
| ERR_GROUP_JOIN_NOT_ALLOWED | Indicates that the user is trying to join the private group. |
| ERR_MEMBER_DELETE_FAILED | Indicates that the API has failed to remove a user from the group. |
| ERR_NO_VACANCY | Indicates that the group is full. |
| ERR_SAME_SCOPE | Indicates that the existing and new scope are same. |
| ERR_MEMBER_SCOPE_CHANGE_FAILED | Indicates that the has failed to change the scope. |
| ERR_NOT_A_BANNED_USER | Indicates that the API is trying to unban non-banned users. |
| ERR_BANNED_GROUPMEMBER | Indicates that the banned user is trying to access the group features. |
| ERR_ALREADY_BANNED | This indicates that the API is trying to ban an already banned user. |
| ERR_MEMBER_BAN_FAILED | Indicates that the API has failed to ban a user from the group. |
| ERR_MEMBER_UNBAN_FAILED | Indicates that the API has failed to unban a user for the group. |
| ERR_GROUP_NO_CLEARANCE | Indicates 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_SCOPE | Indicates that the user does not have admin scope in the group. |
| ERR_GROUP_NO_MODERATOR_SCOPE | Indicates that the user does not have moderator scope in the group. |
| ERR_GROUP_NO_SCOPE_CLEARANCE | Indicates that the user does not have permission to change the scope of other user. |
| ERR_GROUP_NO_SELF_ACTION | Indicates that the user is not allowed to perform an action on himself. For example, changing his own scope. |