Instant Messaging (IM) supports the following group types:
The following table describes the features and limitations of each group type:
Feature Item | Work | Public | Meeting | AVChatRoom |
---|---|---|---|---|
Available member roles | Group owner and ordinary member | Group owner, group admin, and ordinary member | Group owner, group admin, and ordinary member | Group owner and ordinary member |
Requesting to join a group | Unsupported | Supported with group owner or group admin approval required | Supported with no approval required | Supported with no approval required |
Joining the group via invitation by a member | Supported | Unsupported | Unsupported | Unsupported |
Group owner can quit the group | Supported | Unsupported | Unsupported | Unsupported |
Who can modify the group profile | Any group member | Group owner and group admin | Group owner and group admin | Group owner |
Who can kick group members out of the group | Group owner | Group owner and group admin, but group admins can only kick ordinary group members out of the group | Group members cannot be removed. The same effect can be achieved by muting members. | |
Who can mute members | Muting members is not supported | Group owner and group admin, but group admin can only mute ordinary group members | Group owner | |
Unread message count | Supported | Supported | Unsupported | Unsupported |
Viewing historical messages from before a user joined | Unsupported | Unsupported | Supported | Unsupported |
Storage of historical messages on the cloud |
|
Unsupported | ||
Number of groups |
|
|
||
Number of group members |
|
Unlimited number of group members |
Note:
In the Pro Edition or Flagship Edition SDKAppID, the maximum net increase in group quantity per day is 10,000 for all group types by default. The maximum number of free groups is 100,000 per month, and you will need to pay for groups exceeding the free quota.
You can quickly create a group by calling the createGroup API and specifying groupType
, groupID
, and groupName
.
If you want to initialize group information (for example, group introduction, group profile photo, and initial group members) when creating a group, call the createGroup API in the V2TIMGroupManager
management class. The V2TIMGroupManager
management class can be obtained via V2TIMManager.getGroupManager
.
// Sample code: create a work group using the advanced createGroup API
V2TIMGroupInfo v2TIMGroupInfo = new V2TIMGroupInfo();
v2TIMGroupInfo.setGroupName("testWork");
v2TIMGroupInfo.setGroupType("Work");
v2TIMGroupInfo.setIntroduction("this is a test Work group");
List<V2TIMCreateGroupMemberInfo> memberInfoList = new ArrayList<>();
V2TIMCreateGroupMemberInfo memberA = new V2TIMCreateGroupMemberInfo();
memberA.setUserID("vinson");
V2TIMCreateGroupMemberInfo memberB = new V2TIMCreateGroupMemberInfo();
memberB.setUserID("park");
memberInfoList.add(memberA);
memberInfoList.add(memberB);
V2TIMManager.getGroupManager().createGroup(
v2TIMGroupInfo, memberInfoList, new V2TIMValueCallback<String>() {
@Override
public void onError(int code, String desc) {
// Failed to create
}
@Override
public void onSuccess(String groupID) {
// Created successfully
}
});
groupType
is a string. Valid values: “Work”, “Public”, “Meeting”, and “AVChatRoom”. For more information on the differences among group types, see Group Types.groupID
specifies the group ID, which uniquely identifies a group. Do not create groups with the same groupID
in a single SDKAppID. If you set groupID
to null, an ID is assigned for your group by default.groupName
specifies the group description, which has a maximum length of 30 bytes.
The group joining processes for different group types are described below:
Type | Work Group (Work) | Social Networking Group (Public) | Temporary Meeting Group (Meeting) | Live Streaming Group (AVChatRoom) |
---|---|---|---|---|
How to join the group | Must be invited by a group member | User joins the group after request is approved by group owner or admin | User can join freely | User can join freely |
Temporary meeting groups (Meeting) and live streaming groups (AVChatRoom) can be used for interactive scenarios where users join and exit the group frequently, such as online conferences and fashion show live streams. These groups have the simplest join procedure.
After a user successfully joins a group by calling joinGroup, all group members (including the joining user) receive the onMemberEnter callback.
Similar to WeChat and WeChat Work groups, work groups (Work) are suitable for communication in a work environment. The interaction pattern is designed to disable proactive group joining and only allows users to be invited to the group by group members.
A group member calls inviteUserToGroup to invite a user to the group, and then all group members (including the inviter) receive the onMemberInvited callback.
Social networking groups (Public) are similar to the interest groups and tribes in QQ. Any user can request to join the group, but will not become a member of the group until the request is approved by the group owner or admin. While approval is required by default, the group owner or admin can call the setGroupInfo API to set the group joining option (V2TIMGroupAddOpt
) to “forbid anyone to join” or “disable the approval process”.
The following diagram illustrates the process of group joining that requires approval:
isAgreeJoin
is true
, the request is approved. Otherwise, the request is rejected. If the request is approved, all members (including the requestor) receive the onMemberEnter callback.
Call quitGroup to quit a group. The user who quits the group then receives the onQuitFromGroup callback and other group members receive the onMemberLeave callback.
Note:
The group owners of social networking groups (Public), temporary meeting groups (Meeting), and live streaming groups (AVChatRoom) are not allowed to quit the group. Instead, the group owner can disband the group.
Call dismissGroup to disband a group. Then all group members receive the onGroupDismissed callback.
Note:
- For social networking groups (Public), temporary meeting groups (Meeting), and live streaming groups (AVChatRoom), the group owner can disband the group at any time.
- For work groups (Work), the group owner does not have the permission to disband the group. To disband the group, you must have your business server call the RESTful API for disbanding groups.
Call getJoinedGroupList to get a list of work groups (Work), social networking groups (Public), and temporary meeting groups (Meeting) the current user has joined. Live streaming groups (AVChatRoom) will not be included in this list.
Call getGroupsInfo to get the group profile of one or more groups at a time. To get the group profiles of multiple groups with a single call, pass in multiple groupIDs
at one time.
Call setGroupInfo to modify the group profile. When the modification is complete, all group members receive the onGroupInfoChanged callback.
Note:
- For work groups (Work), all group members can modify the basic group profile.
- For social networking groups (Public) and temporary meeting groups (Meeting), only the group owner and admin can modify the basic group profile.
- For live streaming groups (AVChatRoom), only the group owner can modify the group profile.
// Sample code: modify the group profile
V2TIMGroupInfo v2TIMGroupInfo = new V2TIMGroupInfo();
v2TIMGroupInfo.setGroupID("the ID of the group for which you want to modify the group profile");
v2TIMGroupInfo.setFaceUrl("http://xxxx");
V2TIMManager.getGroupManager().setGroupInfo(v2TIMGroupInfo, new V2TIMCallback() {
@Override
public void onError(int code, String desc) {
// Failed
}
@Override
public void onSuccess() {
// Successful
}
});
Any group member can call the setReceiveMessageOpt API to modify the group message receiving option. Available values are as follows:
The group message receiving option allows you to mute group messages:
V2TIMGroupInfo.V2TIM_GROUP_NOT_RECEIVE_MESSAGE
, no group message will be received, and the conversation list will not be updated.With the group message receiving option set toNote:
The unread count feature needs to be enabled for this to work. Therefore it only applies to work groups (Work) and social networking groups (Public).
V2TIMGroupInfo.V2TIM_GROUP_RECEIVE_NOT_NOTIFY_MESSAGE
, when new group messages are received and the conversation list needs to update, get the unread count through getUnreadCount. Use getRecvOpt to verify that the group message receiving option is V2TIMGroupInfo.V2TIM_GROUP_RECEIVE_NOT_NOTIFY_MESSAGE
and then display a badge without the unread count.Based on API 2.0, we designed new custom group fields called "group attributes". Their features are as follows:
Based on group attributes, we can manage the mic for voice chat rooms. When a member turns the mic on, you can set a group attribute to manage the information of the mic-on member. When the member turns the mic off, you can delete the corresponding group attribute. Other members can obtain the group attribute list to show the mic position list.
Call initGroupAttributes to initialize group attributes. The original group attributes, if any, will be cleared.
Call setGroupAttributes to set group attributes. If a set group attribute does not exist, it will be automatically added.
Call deleteGroupAttributes to delete the specified group attribute. If the keys
field is set to null
, all group attributes will be cleared.
Call getGroupAttributes to obtain the specified group attribute. If the keys
field is set to null
, all group attributes will be obtained.
If any group attribute is updated, all group attributes will be updated via the onGroupAttributeChanged callback.
Call getGroupMemberList to get the list of members of a specified group. The list contains profile information about individual members, such as user ID (userID
), group name card (nameCard
), profile photo (faceUrl
), nickname (nickName
), and time of joining the group (joinTime
).
As a group may have a large number of members (even over 5,000), so this API supports two advanced properties: filter
and nextSeq
.
When calling getGroupMemberList, you can specify filter
to pull the information list of certain group roles.
Filter | Description |
---|---|
V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_ALL | Pull the information list of all group members |
V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_OWNER | Pull the information list of the group owner |
V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_ADMIN | Pull the information list of the group admin |
V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_COMMON | Pull the information list of ordinary group members |
// Sample code: pull the profile of the group owner using the filter parameter
int role = V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_OWNER;
V2TIMManager.getGroupManager().getGroupMemberList("testGroup", role, 0,
new V2TIMValueCallback<V2TIMGroupMemberInfoResult>() {
@Override
public void onError(int code, String desc) {
// Failed to pull
}
@Override
public void onSuccess(V2TIMGroupMemberInfoResult v2TIMGroupMemberInfoResult) {
// Pulled successfully
}
});
In many cases, it makes more sense for the user interface to display the first page of the group member list instead of the complete list. More group members can be pulled when the user clicks "Next Page" or pull the list to refresh. For this scenario, you can apply the method of pulling paginated results.
The getGroupMemberList API returns a maximum of 50 members at a time. You can use the pagination flag nextSeq
to pull a paginated group member list. In the first attempt to pull the group member list, enter 0 for nextSeq
. When the first pull succeeds, getGroupMemberList
’s callback result V2TIMGroupMemberInfoResult contains the getNextSeq() API.
V2TIMGroupMemberInfoResult
returned from the previous pull as parameter to the getGroupMemberList API.// Sample code: pull paginated group member list using nextSeq
{
...
long nextSeq = 0;
getGroupMemberList(nextSeq);
...
}
public void getGroupMemberList(long nextSeq) {
int filterRole = V2TIMGroupMemberFullInfo.V2TIM_GROUP_MEMBER_FILTER_ALL;
V2TIMManager.getGroupManager().getGroupMemberList("testGroup", filterRole, nextSeq,
new V2TIMValueCallback<V2TIMGroupMemberInfoResult>() {
@Override
public void onError(int code, String desc) {
// Failed to pull
}
@Override
public void onSuccess(V2TIMGroupMemberInfoResult groupMemberInfoResult) {
if (groupMemberInfoResult.getNextSeq() != 0) {
// Make another pull
getGroupMemberList(groupMemberInfoResult.getNextSeq());
...
} else {
// Pull ends
}
}
});
}
To obtain the profile of a group member, call the getGroupMembersInfo API. You can pass in multiple userID
values at one time to obtain profiles of groups, which improves network transmission efficiency.
The group owner or admin can call the setGroupMemberInfo API to modify group-related information for members, including group name card (nameCard
), group member role (role
), and muting duration (muteUntil
).
The group owner or admin can mute a group member and set a muting duration (in seconds) via muteGroupMember. Muting information is stored in the muteUtil field of the group member. After the group member is muted, all group members (including the muted member) receive the onGroupMemberInfoChanged callback.
The group owner or admin can mute the entire group via the setGroupInfo API by setting allMuted to true
. There is no time limit for muting the group. The group can be unmuted through setAllMuted(false)
in the group profile.
The group owner or admin can call the kickGroupMember API to remove a group member. As a live streaming group (AVChatRoom) can have unlimited members, it does not support this API. You can use muteGroupMember to achieve the same effect instead.
After the member is removed, all group members (including the removed member) receive the onMemberKicked callback.
The group owner can call setGroupMemberRole to change the role of a member of a social networking group (Public) or temporary meeting group (Meeting). Roles available for changing are ordinary member and group admin.
The group owner can call transferGroupOwner to transfer the ownership of the group to another group member.
After the group ownership is transferred, all group members receive the onGroupInfoChanged callback, where the type of V2TIMGroupChangeInfo
is V2TIMGroupChangeInfo.V2TIM_GROUP_INFO_CHANGE_TYPE_OWNER
and the value is the UserID of the new group owner.
Yes, but since live streaming groups (AVChatRoom) do not support storing message history in the cloud, it cannot pull the messages that were sent when it was disconnected.
Verify the group type:
Temporary meeting groups (Meeting) and live streaming groups (AVChatRoom) are designed for conference and live streaming scenarios respectively, and they do not support the unread count feature.
Was this page helpful?