Group System
Group System Overview
The group system is an instant messaging system that allows multiple participants to communicate in one chat. The group system has the following basic capabilities:
Comprehensive group management capabilities: Group creation and disbanding, member management, group profile management, member profile management, and more.
Stable and reliable messaging and a sophisticated group message management mechanism: Permission control, muting/unmuting, message callback, message roaming, and more.
Based on common use cases, Chat provides the following default group types: Work , Public , Meeting , AVChatRoom , and Community .
Upper limit on the number of group members:
The number of members in a Work, Public, or Meeting group can be increased to a maximum of 6,000 if fees are paid. For more information, see Pricing.
A Community group supports up to 100,000 members per group.
There is no upper limit on the number of members in an AVChatRoom.
Note:
Although AVChatRoom supports unlimited group members, if a spike in group members is expected within a short time (in scenarios such as large online events where the number of members in a single group reaches 50,000 or above), contact Tencent Cloud Customer Service in advance and notify for resource allocation by providing the SDKAppID and the expected event time.
Currently, historical message storage is available only for non-AVChatRoom groups, with messages stored for 7 days for the Trial Edition and Standard Edition, 30 days for the Pro Edition, and 90 days for the Pro Plus Edition and Enterprise Edition by default. If you require a longer storage period, change the storage period of historical messages in the console. Increasing the storage period of historical messages is a value-added service. For more information on pricing, see Pricing.
Community is a new powerful tool for entertainment collaboration. Within the same community, a high number of members can be divided into different groups and topics to separate messages for hierarchical communication, yet they can also share the same set of friend relationships. This helps you develop a unique path of social expansion. The community feature is widely suitable for diverse use cases, such as finding like-minded people, game-based social networking, fan marketing, and organization management.
The Community feature is supported by the SDK of the Enhanced edition on v5.8.1668 or later and the SDK for web on v2.17.0 or later. You need to purchase the Pro edition、Pro Plus edition、Enterprise edition, go to the console, select Group feature configuration, and enable Community.
Chat's group system is highly customizable, allowing you to use:
Group Member Roles
The following table lists various group member roles and their permissions:
Group Member Role | Description | Management Permission |
Ordinary member | An ordinary member has no management permissions. | In a Work group, an ordinary member has the permission to modify the group profile. |
Admin | An admin is appointed by the group owner to assist in managing group members and holds certain management permissions. | Modify the group profile. Remove an ordinary member from the group. Mute an ordinary member, that is, prevent the ordinary member from speaking for a certain period of time. Approve or reject a membership application. Work groups do not support the setting of admins by default. |
Group owner | A group owner is the creator of a group and has the highest level of management permissions in the group. | The group owner has the following permissions in addition to all permissions held by an admin: Appoint or cancel an admin. Remove an admin from the group. Mute an admin. Disband the group. Transfer the group. |
Application Admin | This special role has the authority to manage all group permissions in the app and has more power than the group owner. | The Application Admin has the same permissions as the group owner, whether it is a member of the group or not. |
Group Types
Based on common use cases, Chat provides the following default group types:
Group type | Applicable scenario |
Work | After a Work group is created, users can join the group only after being invited by group members. The invitation does not need to be accepted by the invitee or approved by the group owner. This group type is the same as private group (Private) in earlier versions. |
Public | After a Public group is created, the group owner can designate group admins. To join the group, a user needs to search for the group ID and send a request, and the request needs to be approved by the group owner or an admin before the user can join the group. |
Meeting | A Meeting group allows users to join and leave freely and view historical messages sent before they join the group. Meeting groups are ideal for scenarios that integrate Tencent Real-Time Communication (TRTC), such as audio/video conferencing and online education. This group type is the same as chat room (ChatRoom) in earlier versions. |
AVChatRoom | An AVChatRoom group allows users to join and exit freely, supports an unlimited number of members, and does not store message history. Audio-video groups can be used with Cloud Streaming Services (CSS) to support on-screen comment chat scenarios. |
Community | A Community group allows users to join and exit freely, supports up to 100,000 members, and stores message history. To join the group, a user needs to search for the group ID and send an application, and the application does not need to be approved by an admin before the user can join the group. |
Differences in Basic Group Capabilities
Item | Work | Public | Meeting | AVChatRoom | Community |
Available member roles | Group owner Ordinary member Application admin | Group owner Admin Ordinary member Application admin | Group owner Admin Ordinary member Application admin | Group owner Application admin | Group owner Admin Ordinary member Application admin |
Permission to modify basic group information | Ordinary member Group owner Application admin | Group admin Group owner Application admin | Group owner Application admin | Group owner Application admin | Admin Group owner Application admin |
Ability to Obtain Group Member Information | Can obtain information for all group members | Can obtain information for all group members | Can obtain information for all group members | Cannot obtain information (no group member information stored) | Can obtain information for all group members |
Who can disband a group | Application admin | Group owner and Application Admin | Group owner and Application Admin | Group owner and Application Admin | Group owner and Application Admin |
Note:
Group types have been upgraded in the new SDK version, including Work Group, Public, Meeting Group, AVChatRoom, and Community. Private and ChatRoom in earlier versions (which had Public, Private, ChatRoom, and AVChatRoom groups) correspond to Work Group and Meeting Group in the new version respectively.
Ordinary members of Work Group can modify only the group name, introduction, announcement, and group profile photo URL, but not other group profile information.
If the roles within a group type cannot meet your business needs, you can add new roles by setting group member-level custom fields.
To retrieve information about some group members, such as in AVChatRoom scenarios where only a partial member list is displayed.
Differences in Joining a Group
Item | Work Group | Public | Meeting Group | AVChatRoom | Community |
Perform an exact search for a group ID to join a group | Not supported | Supported | Supported | Supported | Supported |
Perform a fuzzy search for group information to join a group | Not supported | Not supported | Not supported | Not supported | Not supported |
Request to Join Group | Not supported | Supported. Approval from the group owner or admin is needed. | Supported. No approval is needed. | Supported. No approval is needed. | Supported. No approval is needed. |
Join a group after an invitation from a group member is received | Supported | Not supported | Not supported | Not supported | Supported |
Note:
Exact search is to search for a group by group ID. Fuzzy search is to search for a group by fields such as the group name.
Group join approval: the group owner and Group Administrator can choose to approve or reject applications made by non-members to join the group. Only approved users can join the group.
For a group type that does not support the invitation of non-members to a group, group members can share the group ID with non-members in the app so that the non-members can join the group.
Differences in Member Management Capabilities
Item | Work Group | Public Group | Meeting | AVChatRoom | Community |
Appointing administrators | Not supported | Supported | Supported | Supported | Supported |
A group owner leaves the group | Supported. After the group owner leaves, the group has no group owner. | Not supported | Not supported | Not supported | Not supported |
Kick a group member | Supported. The group owner can kick group members. | Supported. The group owner and administrator can kick group members, but the administrator can kick only ordinary group members. | Supported. The group owner and administrator can kick group members, but the administrator can kick only ordinary group members. | Not supported. The muting feature can be used to achieve a similar effect. | Supported. The group owner and administrator can kick group members, but the administrator can kick only ordinary group members. |
Mute a group member | Not supported | Supported. The group owner and administrator can mute group members, but the administrator can mute only ordinary group members. | Supported. The group owner and administrator can mute group members, but the administrator can mute only ordinary group members. | Supported. The group owner can mute group members. | Supported. The group owner and administrator can mute group members, but the administrator can mute only ordinary group members. |
Periodically remove offline group members | Supported, but disabled by default. | Supported, but disabled by default. | Supported, but disabled by default. | Not supported | Not supported |
Note:
Muted group members cannot send group chat messages within the mute period.
Differences in Group Limits
Item | Work/Public/Meeting | AVChatRoom | Community |
Maximum number of members | Trial edition: 20 per group Standard edition: 500 members/group by default Pro edition：2,000 members/group by default Pro Plus edition：5,000 members/group by default Enterprise edition: 6,000 members/group by default | Unlimited | Trial edition: 100,000 members/group by default Standard edition: not supported Pro edition：100,000 members/group by default Pro Plus edition：1,000,000 members/group by default Enterprise edition: 1,000,000 members/group by default |
Maximum number of groups | Trial edition: up to 100 existing groups, and disbanded groups do not count against the quota. Standard edition, Pro edition, Pro Plus edition, Enterprise edition: unlimited | Trial edition: up to 50 existing groups, and disbanded groups do not count against the quota Standard edition: up to 50 existing groups, and disbanded groups do not count against the quota. You can upgrade to an unlimited number of audio-video groups by purchasing the value-added service. Pro edition, Pro Plus edition, Enterprise edition: unlimited | Trial edition: not supported Standard edition: not supported Pro edition：100,000 members/group by default Pro Plus edition：1,000,000 members/group by default Enterprise edition: 1,000,000 members/group by default |
Caution
Under the Standard or Premium Edition SDKAppID, the daily net increase in group count (excluding communities) is capped at 10,000 (i.e., created group count minus dissolved group count).
In the Standard edition, Pro edition, Pro Plus edition, or Enterprise edition SDKAppID, the free peak group count is 100,000 per month, and you will need to pay fees for exceeding the quota. It is recommend that you disband the groups that are no longer needed in a timely manner.
Differences in Message Capabilities
Feature Item | Work Group | Public Group | Meeting | AVChatRoom | Community |
Unread message count | Supported | Supported | Not supported | Not supported | Supported |
Historical message storage | Supported | Supported | Supported | Not supported | Supported |
Viewing roaming messages from before a user joins the group | Not supported | ||||
Notification of group member change | A notification is pushed and stored in the roaming system by default when a user is invited to a group, requests to join the group, is kicked out of a group, or leaves a group. This feature can be configured in the console. | A notification is pushed and stored in the roaming system by default when a user is invited to a group, requests to join the group, is kicked out of a group, or leaves a group. This feature can be configured in the console. | A notification is disabled by default when a user is invited to a group, requests to join the group, is kicked out of a group, or leaves a group. This feature can be configured in the console. | A notification is pushed but not stored in the roaming system when a user is invited to a group, requests to join the group, is kicked out of a group, or leaves a group. | A notification is pushed and stored in the roaming system by default when a user is invited to a group, requests to join the group, is kicked out of a group, or leaves a group. This feature can be configured in the console. |
Notification of group profile change | A notification is sent and stored for roaming by default when the group name, group notifications, group introduction, group profile photo, or group owner is changed, and a notification is disabled by default when group muting or the group join method is changed. Both can be configured in the console. | A notification is sent and stored for roaming by default when the group name, group notifications, group introduction, group profile photo, or group owner is changed, and a notification is disabled by default when group muting or the group join method is changed. Both can be configured in the console. | A notification is sent and stored for roaming by default when the group name, group notifications, group introduction, group profile photo, or group owner is changed, and a notification is disabled by default when group muting or the group join method is changed. Both can be configured in the console. | A notification is sent but not stored for roaming when the group name, group notifications, group introduction, group profile photo, or group owner is changed, and a notification is disabled when group muting or the group join method is changed. | A notification is sent and stored for roaming by default when the group name, group notifications, group introduction, group profile photo, or group owner is changed, and a notification is disabled by default when group muting or the group join method is changed. Both can be configured in the console. The community join method cannot be changed, so no notification will be sent. |
Notification of group member profile change | A notification is pushed and stored persistently by default when group member muting or Group Administrator is changed. This feature can be configured in the console. | A notification is pushed and stored persistently by default when group member muting or Group Administrator is changed. This feature can be configured in the console. | A notification is disabled by default when group member muting or Group Administrator is changed. This feature can be configured in the console. | A notification is disabled by default when group member muting or Group Administrator is changed. This feature can be configured in the console. | A notification is pushed and stored persistently by default when group member muting or Group Administrator is changed. This feature can be configured in the console. |
A message must be sent to activate a new group | Required | Not required | Not required | Not required | Not required |
Default message receiving option | Receive online and offline push messages | Receive online and offline push messages | Receive only online push messages | Receive only online push messages | Receive online and offline push messages |
Note:
For a group that requires activation, before the group owner sends a message, the group is inactive and invisible to all group members except the group owner. A group that does not require activation is visible to all group members once it is created.
Currently, offline push is available only on Android (Android offline push) and iOS (APNs push) platforms.
Work group, public group, meeting group, and community group can store historical messages for 7 days (30 days for the Pro edition, 90 days for the Pro Plus edition, and 90 days for the Enterprise edition) free of charge by default. If you need a longer storage period, change the storage period of historical messages in the console. Extending the storage period of historical messages is a value-added service. For more information on pricing, see Pricing.
Differences in Batch Import and Automatic Disbanding
Item | Work/Public/Meeting/Community | AVChatRoom |
Importing groups, group members, and group messages is allowed | Yes. It is allowed when historical groups are migrated from a third-party platform to Chat. | No. Only existing groups, group members, and group messages can be used. |
Time before a group is automatically repossessed (in seconds). | The backend does not disband groups, unless the group owner disbands the group or all members leave the group. (About group disbanding: the backend does not proactively disband a group unless the group owner disbands the group or the group is automatically disbanded. If automatic disbanding is configured for a group, the backend periodically checks the group and disbands it if no one sends a message in the group for n seconds or the group profile is modified.) | The backend does not disband groups, unless the group owner disbands the group or all members leave the group. |
Group Data Structure
Group Basic Information
Field Name | Type | Description | Notes |
GroupId | String | Unique identifier of the group | Read-only. Each group ID must be unique in the app. The prefix is @TGS#, and custom group IDs can also be used in the app. |
Type | String | Group type | Read-only. The following group types are supported by default: work group, public group, meeting group, AVChatRoom, and community. For more information, see Group Types. In the SDK of an earlier version, group types also include the private group, ChatRoom, and BChatRoom, which are not recommended. |
Name | String | Name of the group | Readable and writable. The maximum length is 30 bytes and cannot be adjusted. |
Introduction | String | Introduction of the group | Readable and writable. The maximum length is 240 bytes and cannot be adjusted. |
Notification | String | Group announcement | Readable and writable. The maximum length is 300 bytes and cannot be adjusted. |
FaceUrl | String | URL of the group's Avatar | Readable and writable. The maximum length is 100 bytes and cannot be adjusted. |
Owner_Account | String | ID of the group owner | Read-only. |
CreateTime | Integer | Creation time of the group | Read-only. |
InfoSeq | Integer | This value increases every time the group profile changes. | Read-only. |
LastInfoTime | Integer | Time of the last change to group profile | Read-only. |
LastMsgTime | Integer | Time of the last message in the group chat | Read-only. |
NextMsgSeq | Integer | Seq of the next message in the group | Read-only. Every message in the group has a unique Seq, and the Seq values are consecutive numbers based on the sequence of sent messages. With every message sent to the group, NextMsgSeq (starting from 1) increases by 1 (by default, system messages such as notifications of group join or leaving are messages and can cause NextMsgSeq to increase by 1). |
MemberNum | Integer | Number of current members | Read-only. |
MaxMemberNum | Integer | Maximum number of members | Default value: The subscription limit; for example, it is 20 for the Trial Edition. If you upgrade your plan, you need to modify this field to the corresponding value according to the basic information of the modified group. |
ApplyJoinOption | String | Membership application option | The following options are available: DisableApply: prohibit any join requests. NeedPermission: group owner or admin's approval is required. FreeAccess: users can join the group freely without prior approval. |
Note:
The permissions to modify the group name, introduction, announcement, and profile photo URL are described as follows:
In a work group, any member can modify them.
For other group types, only non-ordinary members can modify them.
Group Member Profile
Field Name | Type | Description | Notes |
Member_Account | String | Group member ID | Read-only. |
Role | String | Role in the group | A group has the following roles: Owner (group owner), Admin (group admin), and Member (group member). |
JoinTime | Integer | Time of joining the group | Read-only. |
MsgSeq | Integer | Sequence number of the current read message of the member | Read-only. |
MsgFlag | String | Message receiving option | The following options are available: AcceptAndNotify: Accept and notify. AcceptNotNotify means accept without notifying (does not trigger Offline Push) Discard: block group messages (messages are not pushed to clients) AcceptNotNotifyExceptAt means accept and notify for '@' messages (Only '@' messages trigger Offline Push, other messages do not trigger) |
LastSendMsgTime | Integer | Time of sending the last message | It supports three ordinary groups, but does not support AVChatRoom. It can only be used by server-side APIs. |
NameCard | String | Group name card | Readable and writable. It can contain up to 50 bytes and cannot be adjusted. |
MuteUntil | Integer | Muting status | If it is 0, the group member is not muted; otherwise, it indicates the muting stop timestamp. |
Permission Group Information
Field Name | Type | Description | Notes |
PermissionGroupId | String | Unique identifier of the permission group | Read-only |
PermissionGroupName | String | Name of the permission group | Readable and writable. It can contain up to 150 bytes and cannot be adjusted. |
Permission | Integer | Permissions of the permission group | Readable and writable. It is a 64-bit integer, and each bit represents a management permission. |
CustomString | String | Custom field of the permission group | Readable and writable. It contains up to 3,000 bytes. The business layer can use this field for implementing requirements in special scenarios. |
MemberNum | Integer | Number of members in the permission group | Read-only |
CreateTime | Integer | Creation time of the permission group | Read-only |
Permissions in the Permission Group
Management of permissions within a group is primarily accomplished through the permissions detailed in the permission group information and those related to topics. Each bit represents a permission. When a permission bit is set to 1, this permission is granted.
Meanings of Permissions in the Permission Group
Permission Name | Description | Permission Bits and Their Values |
ManageGroupInfo | Permission for modifying the group profile | 1<<0 (left shift to 0 bit, the same below) |
ManageGroupMember | Permission for adding/deleting members to/from a group or modifying group member information | 1<<1 |
ManagePermissionGroupInfo | 1. Permission for creating, modifying, and deleting permission groups 2. Permission for setting permission groups (Add, Modify, and Delete) in all topics | 1<<2 |
ManagePermissionGroupMember | Permission for adding/deleting members to/from a permission group | 1<<3 |
ManageTopic | Permission for creating, modifying, and deleting topics | 1<<4 |
GroupMuteMember | Permission for muting group members | 1<<5 |
SendGroupMessage | Permission for sending messages in the community | 1<<6 |
GroupAtAll | Permission for using @all when sending messages in the community | 1<<7 |
GetGroupHistoryMessage | Permission to get history messages before joining the group | 1<<8 |
RevokeOtherMemberGroupMessage | Permission for revoking group messages of others | 1<<9 |
BanMemberGroupMessage | Permission for banning group members | 1<<10 |
Topic Permissions
Permission Name | Description | Permission Bits and Their Values |
ManageTopicInfo | Permission for modifying and deleting topics | 1<<0 (left shift to 0 bit, the same below) |
ManagePermissionTopicInfo | Permission for setting permission groups (Add, Modify, and Delete) in this topic | 1<<1 |
TopicMuteMember | Permission for muting members in topics | 1<<2 |
SendTopicMessage | Permission for sending messages in topics | 1<<3 |
GetTopicHistoryMessage | Permission for getting history messages before the member joins the topic | 1<<4 |
RevokeOtherMemberTopicMessage | Permission for revoking topic messages of others | 1<<5 |
TopicAtAll | Permission for using @all when sending messages in topics | 1<<6 |
Custom Group IDs
When a group is created in the app, Chat assigns a default group ID to the new group. This default group ID starts with @TGS# and is unique in the app.
Chat also allows you to customize group IDs that are simple and easy to remember and communicate. A custom group ID must be a string of ASCII characters (0x20-0x7e) with a length less than 48 bytes. Do not use @TGS# as the prefix to avoid confusion with default group IDs.
Note:
The group ID prefix for Community groups must be @TGS#_.
Custom Topic IDs
When a topic is created in the app, Chat assigns a default topic ID to the new topic by default. The ID starts with
GroupId+@TOPIC#_ and is unique in the group.To make it easier to remember and communicate the topic ID, Chat allows customizing it in the format of
GroupId+@TOPIC#_+ custom part during topic creation through the RESTful API in the application. The custom part cannot contain @TGS#_ and @TOPIC#_@TOPIC# (to avoid confusion with the default group ID) and must consist of printable ASCII characters (0x20-0x7e).For example, if
GroupId is @TGS#_@TGS#cQVLVHIM62CJ, and the custom part is TestTopic, the custom topic ID will be @TGS#_@TGS#cQVLVHIM62CJ@TOPIC#_TestTopic. The entire custom topic ID must be no longer than 96 bytes.Customizing Permission Group IDs
By default, when an app creates a permission group, Chat assigns a default permission group ID to the newly created group. This ID will start with @PMG#_@PMG# and is unique within the group.
To make the permission group ID simpler and easier to remember and disseminate, Chat supports app in customizing the permission group ID through the RESTful API when creating a permission group. The custom permission group ID must start with @PMG#_ (but not with @PMG#_@PMG# to avoid confusion with the default assigned permission group ID) and be printable ASCII characters (
0x20-0x7e ).Custom Fields
Chat allows you to configure up to 10 group-level custom fields and 5 member-level custom fields based on your business needs. With custom fields, apps can attach additional data to groups, and the data can be read and written through existing APIs.
Description
Custom fields have the following characteristics:
Custom fields are structured in key-value format.
Key is a string with a maximum length of 16 bytes. Its name can only contain uppercase and lowercase letters, numbers, and underscores (_).
Value is a buffer customized by the user, which can be binary data. Group-level values have a maximum length of 512 bytes, while member-level values have a maximum length of 64 bytes.
You can configure the minimum read permission and minimum write permission for each key.
The read and write permissions of a custom field are listed as follows, from high to low:
1. Readable and writable by the application administrator.
2. Readable and writable by the group owner.
3. Readable and writable by the group admin.
4. Readable and writable by group members.
5. Readable and writable by anyone, including non-members.
For example, an app needs to extend the
GroupLevel field for groups and the value of this field is a number representing the level of a group. If this level information is calculated by the app backend, then the least write permission should be writable by the Application Administrator. If the field is part of the Group Profile, its least read permission should be readable by anyone, including non-members. If the value to be stored is a number, we recommend that C and C++ developers store it as a string instead of binary data. For example, when the number to be stored is 1, store it as string
1 instead of binary data 0x01. In the future, Chat will offer more operations for custom fields, such as specific mathematical operations on values, which will be performed on the basis of string-type numbers.Configuration
Custom fields at these two levels can be configured in the Instant Messaging Chat console.
To configure member-level custom fields, you need to specify the group type first. AVChatRoom and custom group types that are configured based on it do not support custom fields at the group member level, because these types of groups do not store member profiles.
The self read and write permissions indicate whether members can read and write their own member-level custom fields. For example, a member-level custom field named
MemberLevel represents the level of a member in a group. Group members can read but not modify their own levels, and therefore their self read and write permissions are set to readable/unwritable for this field.Note:
Configured custom fields cannot be deleted or modified. Proceed with caution.
Custom Callbacks
Third-party callback is an important means to meet the special requirements of apps. It provides users with the capability to customize actions.
Instant Messaging Chat's group system supports different webhooks. For more information, see Third-Party Webhook Overview and Webhook Command List.
