The group system is an instant messaging system that allows multiple participants to communicate in 1 chat. The group system has the following basic capabilities:
Note:
- Although AVChatRooms support unlimited group members, if a spike in group members is expected within a short time (in scenarios such as large online events where members in a single group exceed 50,000), contact sales representatives in advance and report service resource usage by providing the SDKAppID and the scheduled event time.
- Currently, historical message storage is available only for non-AVChatRoom groups, with messages stored for 7 days for billing plans of the Trial Edition and Pro Edition and 30 days for the Flagship 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.
IM's group system is highly customizable, allowing you to use:
The following table lists various group member roles and their permissions:
Group Member Role | Description | Management Permissions |
---|---|---|
Ordinary member | An ordinary member has no management permissions. | In a work group (Work), 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. |
|
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:
|
App admin | This special role has the authority to manage all group permissions in the app and has more power than the group owner. | The app admin has the same permissions as the group owner, whether it is a member of the group or not. |
By default, the group system supports the following group types for common use cases:
Group Type | Applicable Scenario |
---|---|
Work group (Work) | Similar to an ordinary WeChat group. After a work group is created, only a group member can invite other users to join this group, and the invitation does not need to be approved by the invited user or group owner. |
Public group (Public) | Similar to a QQ group. After a public group is created, the group owner can specify a group admin. When a user searches for the group ID and initiates a request to join the group, the request must be approved by the group owner or admin before the user can join the group. |
Meeting group (Meeting) | After a meeting group is created, a user can join and quit the group as desired, and view messages sent before the user joined the group. This group type is suitable for scenarios where real-time audio/video services are used, for example, audio and video conferencing and online education. |
Audio-video chat room (AVChatRoom) | After an AVChatRoom is created, a user can join and quit the group as desired. This group type does not limit the number of members, but it does not support storage of historical messages. It can be used together with Live Video Broadcasting (LVB) to support on-screen comments. |
Item | Work Group | Public Group | Meeting Group | AVChatRoom |
---|---|---|---|---|
Available member roles | Group owner Ordinary member App admin |
Group owner Admin Ordinary member App admin |
Group owner Admin Ordinary member App admin |
Group owner Ordinary member App admin |
Modify basic group information | Ordinary member | Group admin Group owner App admin |
Group owner App admin |
App admin |
Obtain group member information | Information of all group members | Information of all group members | Information of the first 300 group members | None group member information |
Disband a group | Only the app admin can disband a group. | The group owner and group admin can disband the group. | The group owner and group admin can disband the group. | The group owner and group admin can disband the group. |
Note:
- Ordinary members of a work group (Work) can modify only the group name, introduction, announcement, and group profile photo URL, but not other basic group information.
- If the roles of a group type cannot meet your business needs, you can add roles by setting member-level custom fields.
- It is necessary to obtain the information about some members in scenarios where an AVChatRoom displays a list of some of its members.
Item | Work Group | Public Group | Meeting Group | AVChatRoom |
---|---|---|---|---|
Perform an exact search for a group ID to join a group | Not supported | Supported | Supported | Supported |
Perform a fuzzy search for group information to join a group | Not supported | Not supported | Not supported | Not supported |
Apply to join a group | Not supported | Supported. Approval from the group owner or admin is needed. | Supported. No approval is needed. | Supported. No approval is needed. |
Join a group after receiving an invitation from a group member | Supported | Not supported | Not supported | Not supported |
Note:
- Exact search: search for a group by group ID. Fuzzy search: search for a group by fields such as the group name.
- Approval for joining a group: the group owner and admin 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.
Item | Work Group | Public Group | Meeting Group | AVChatRoom |
---|---|---|---|---|
Set an admin | Not supported | Supported | Supported | Not supported |
A group owner quits the group | Supported. After the group owner quits, the group has no group owner. | Not supported | Not supported | Not supported |
Remove a group member | Supported. The group owner can remove group members. | Supported. The group owner and admin can remove group members, but the admin can remove only ordinary group members. | Supported. The group owner and admin can remove group members, but the admin can remove only ordinary group members. | Not supported. The muting feature can be used to achieve a similar effect. |
Mute a group member | Not supported | Supported. The group owner and admin can mute group members, but the admin can mute only ordinary group members. | Supported. The group owner and admin can mute group members, but the admin can mute only ordinary group members. | Supported. The group owner can mute group members. |
Periodically remove offline group members | Supported, but disabled by default | Supported, but disabled by default | Supported, but disabled by default | Not supported |
Note:
Muted group members cannot send group chat messages.
Item | Work Group/Public Group/Meeting Group | AVChatRoom |
---|---|---|
Maximum number of members |
|
Unlimited |
Maximum number of groups |
|
|
Note:
- For an SDKAppID of the Pro Edition or Flagship Edition, up to 10,000 groups regardless of the group type (the number of created groups minus the number of disbanded groups) can be added in a day.
- For an SDKAppID of the Pro Edition or Flagship Edition, up to 100,000 groups can be added for free in a month. If this quota is exceeded, fees for usage exceeding the free quota will be charged. It is recommend that you disband the groups that are no longer needed in a timely manner.
Item | Work Group | Public Group | Meeting Group | AVChatRoom |
---|---|---|---|---|
Unread count is supported | Yes | Yes | No | No |
Group members can view messages sent before they join the group | No | No | Yes | No |
Historical message storage is supported | Yes | Yes | Yes | No |
Member change notifications are supported | Yes | Yes | No | Yes |
A message must be sent to activate a new group | Yes | No | No | No |
Default message receiving option | Receive online and offline pushed messages | Receive online and offline pushed messages | Receive only online pushed messages | Receive only online pushed messages |
Users can receive group messages as guests without logging in | No | No | No | Yes |
Note:
- A group that requires activation is inactive before the group owner sends a message and is invisible to all group members except the group owner. A group that does not require activation is visible to all group members once created.
- Currently, offline push is available only on Android (Android offline push) and iOS (APNs push) platforms.
- The work group, public group, and meeting group have the historical message storage capability, which allows historical messages to be stored for 7 days (30 days for the Flagship Edition) free of charge by default. If you need 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.
Item | Work Group/Public Group/Meeting Group | 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 IM. | 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 repossess a group, unless the group owner disbands the group or all members quit the group. | The backend does not repossess a group, unless the group owner disbands the group or all members quit the group. |
Note:
To enable group repossession, submit a ticket. After configuration, inactive groups will be cleaned up by group type. An inactive group is a group in which no messages are sent and no member changes occur.
Field Name | Type | Description | Notes |
---|---|---|---|
GroupId | String | Unique identifier of the group | Read-only The ID of the group, which 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, and AVChatRoom. 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 to 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 profile photo | 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 information changes. | Read-only |
LastInfoTime | Integer | Time of the last change to group information | 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 chat | Read-only Every message in the group chat has a unique message Seq. Seq values are continuous based on the sequence of sent messages. With every message sent in the group chat, NextMsgSeq (starting from 1) increases by 1. |
MemberNum | Integer | Number of current members | Read-only |
MaxMemberNum | Integer | Maximum number of members | - |
ApplyJoinOption | String | Membership application option | The following options are available:
|
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.
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 | Current read message Seq of the member | Read-only |
MsgFlag | String | Message receiving option | The following options are available:
|
LastSendMsgTime | Integer | Time of sending the last message | Read-only |
NameCard | String | Group name card | Readable and writable |
If the group types provided by IM cannot meet your needs, you can submit a ticket to apply to modify existing group types or add custom group types.
For example, you can create a group that is used in an office environment. This group is similar to a work group, but every member has the highest level of management permissions and can view messages sent before they join the group. In this case, you can:
Note:
- When creating a group type, you must specify a group type as a reference type. Note that BChatRoom in SDK of earlier versions cannot be specified as a reference type.
- After configuration, the new group type will have new features that are specified in the ticket, and the same features as the reference type.
When a group is created in the app, IM assigns a default group ID to the new group by default. This default group ID starts with @TGS# and is unique in the app.
IM 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 assigned group IDs.
IM allows you to configure up to 20 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 read and write data through existing APIs. Custom fields cannot be deleted once created and applied.
Custom fields have the following characteristics:
The read and write permissions of a custom field are as follows, from high to low:
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 app admin. If the field is part of the public profile of the group, 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, IM 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.
Custom fields at these 2 levels can be configured in IM 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 self read and write permissions are set to readable/unwritable for this field.
Third-party callback is an important means to meet the special requirements of apps. It provides users with the capability to customize actions.
IM's group system supports different callbacks. For more information, see Third-Party Callback Overview and List of Callback Commands.
Was this page helpful?