Instant Messaging (IM) supports the following group types:
The following table describes the features and limitations of each group type:
Feature | Work Group (Work) | Public Group (Public) | Meeting Group (Meeting) | Community Group (Community) | Audio-Video Group (AVChatRoom) |
---|---|---|---|---|---|
Available member roles | Group owner and common member | Group owner, group admin, and common member | Group owner, group admin, and common member | Group owner, group admin, and common member | Group owner and common member |
Requesting to join a group | Not supported | Supported with group owner or admin approval required | Supported with no approval required | Supported with no approval required | Supported with no approval required |
Joining group via invitation by a member | Supported | Not supported | Not supported | Supported | Not supported |
Group owner leaving group | Supported | Not supported | Not supported | Not supported | Not supported |
Who can modify group profile | Any group member | Group owner and admin | Group owner and admin | Group owner and admin | Group owner |
Who can kick group members out of group | Group owner | Group owner and admin. Group admin can only remove common group members. | 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 admin. Group admin can only mute common group members. | Group owner | ||
Unread count | Supported | Supported | Not supported | Supported | Not supported |
Viewing message history from before the user joined the group | Supports console configuration | Supports console configuration | Supports console configuration | Supports console configuration | Not supported |
Group member change notifications | Supports console configuration | Supports console configuration | Supports console configuration | Supports console configuration | Not supported |
Group profile change notifications | Supports console configuration | Supports console configuration | Supports console configuration | Supports console configuration | Not supported |
Group member profile change notifications | Supports console configuration | Supports console configuration | Supports console configuration | Supports console configuration | Supports console configuration |
Retaining message history in the cloud |
|
Not supported | |||
Number of groups |
|
|
|
||
Number of group members |
|
100,000 | Unlimited number of group members |
Note:
- Group types are upgraded in the new SDK version and they are work group (Work), public group (Public), meeting group (Meeting), community group (Community), and audio-video group (AVChatRoom). Private group (Private) and chat room (ChatRoom) in earlier versions (which have Public, Private, ChatRoom, and AVChatRoom groups) correspond to work group (Work) and meeting group (Meeting) in the new version respectively.
- In the Pro Edition or Ultimate Edition SDKAppID, the maximum net increase in group count per day is 10,000 for all group types. Free peak group count is 100,000 per month, and you will need to pay for usage not covered by the free quota.
- Community group (Community) is supported only in native SDK 5.8.1668 enhanced edition or higher and web SDK 2.17.0 or later. To use the feature, you need to purchase the Ultimate Edition package and apply for activation.
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: Use the advanced `createGroup` API to create a work group
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) {
// Creation failed
}
@Override
public void onSuccess(String groupID) {
// Group created successfully
}
});
groupType
is a string and can be one Work
, Public
, Meeting
, or AVChatRoom
. For the differences between 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 SDKAppID. If you set groupID
to null
, you will be assigned a group ID by default.groupName
specifies the group description, which can have a maximum length of 30 bytes.The group joining method varies according to the group type, as described below:
Group Type | Work Group (Work) | Public Group (Public) | Meeting Group (Meeting) | Community Group (Community) | Audio-Video Group (AVChatRoom) |
---|---|---|---|---|---|
Group Joining Method | Users must be invited by group member. | Users can join the group only after their requests are approved by group owner or admin. | Users can join the group freely. | Users can join the group freely. | Users can join the group freely. |
Meeting groups (Meeting) and audio-video groups (AVChatRoom) can be used for interactive scenarios where users join and leave groups frequently, such as online conferencing and show live streaming. The group joining procedure is therefore the simplest.
After a user successfully joins a group by calling joinGroup, all group members (including the joined user) receive the onMemberEnter callback.
Work groups (Work) are suitable for communication in work environments. The interaction pattern is designed to disable proactive group joining and only allow users to be invited to join the group by group members.
A group member calls inviteUserToGroup to invite a user to the group, then all group members (including the inviter) receive the onMemberInvited callback.
Public 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 which is tighter, or to disable the approval process, which is more flexible.
The following diagram illustrates the process of group joining that requires approval:
isAgreeJoin
is true
, the request is accepted. Otherwise, the request is rejected. If the request is accepted, all members (including the requester) receive the onMemberEnter callback.Call quitGroup to leave a group. The user who leaves the group then receives the onQuitFromGroup callback and other group members receive the onMemberLeave callback.
Note:For a public group (Public), meeting group (Meeting), community group (Community), or audio-video group (AVChatRoom), the group owner is not allowed to leave the group but can disband the group.
Call dismissGroup to disband a group. Then all group members receive the onGroupDismissed callback.
Note:
- For a public group (Public), meeting group (Meeting), community group (Community), or audio-video group (AVChatRoom), the group owner can disband the group at any time.
- For a work group (Work), the group owner does not have the permission to disband the group. To disband the group, you must have your service server call the RESTful API.
Call getJoinedGroupList to get a list of work groups (Work), public groups (Public), meeting groups (Meeting), and community groups (Community) the current user has joined. Audio-video 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 by a single call, pass in multiple groupID
values at a time.
Call setGroupInfo to modify the group profile. When the modification is completed, all group members receive the onGroupInfoChanged callback.
Note:
- For work groups (Work), all group members can modify the basic group profile.
- For public groups (Public), meeting groups (Meeting), and community groups (Community), only the group owner and admin can modify the group profile.
- For audio-video groups (AVChatRoom), only the group owner can modify the group profile.
// Sample code: Modify 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 setGroupReceiveMessageOpt API to modify the group message receiving option. Available values are as follows:
The group message receiving option allows you to mute group messages:
V2TIMMessage.V2TIM_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:This mode requires the unread count feature and therefore it applies only to work groups (Work) and public groups (Public).
V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE
, when new group messages are received and the conversation list needs to be updated, you can get the unread count through getUnreadCount. Use getRecvOpt to verify that a red dot instead of the unread count is displayed when the group message receiving option is V2TIMMessage.V2TIM_RECEIVE_NOT_NOTIFY_MESSAGE
.New custom group fields, also called group attributes, are designed based on API 2.0. They have the following features:
initGroupAttributes
, setGroupAttributes
, and deleteGroupAttributes
APIs each can be called by the SDK for up to ten times per five seconds, and the error code 8511 will be called back if the limit is exceeded. The APIs each can be called by the backend for up to five times per second, and the error code 10049 will be called back if the limit is exceeded.getGroupAttributes
API can be called by the SDK for up to 20 times per five seconds.With group attributes, you can manage the seats of audio chat rooms. When a user mics on, you can set a group attribute to manage the information of the user. When the user mics off, you can delete the group attribute. Other members can get the list of group attributes to display the seat list.
Call the initGroupAttributes API to initialize group attributes. If the group has existing group attributes, they will be deleted first.
Call the setGroupAttributes API to set group attributes. If the group attributes to set do not exist, they will be automatically added.
Call the deleteGroupAttributes API to delete specified group attributes. If you set the keys
parameter to null
, all group attributes will be deleted.
Call the getGroupAttributes API to get specified group attributes. If you set the keys
parameter to null
, all group attributes will be returned.
If any group attribute is updated, all group attribute fields will be called back via onGroupAttributeChanged.
Call getGroupMemberList to get the list of group members of a given group. The list contains profile information about individual members, such as user ID (userID
), group name card (nameCard
), profile photo (faceUrl
), nickname (nickName
), and group joining time (joinTime
).
As a group might have a large number of members (for example, over 5,000), this API supports two advanced features: filter (filter
) and pulling by page (nextSeq
).
filter
)When calling the getGroupMemberList API, you can specify filter
to pull the information of certain 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 common 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) {
// Messages failed to be pulled
}
@Override
public void onSuccess(V2TIMGroupMemberInfoResult v2TIMGroupMemberInfoResult) {
// Pulled successfully
}
});
nextSeq
)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 scroll down the list to refresh. For this scenario, you can apply the method of pulling by page.
The getGroupMemberList API returns a maximum of 50 members at a time. You can use the pagination flag nextSeq
to pull the group member list by page. In the first attempt to pull the group member list, enter 0
for nextSeq
. When the first pull succeeds, the callback result V2TIMGroupMemberInfoResult contains the getNextSeq() API.
0
, the complete group member list has been pulled.V2TIMGroupMemberInfoResult
returned from the previous pull as a parameter to the getGroupMemberList API.// Sample code: Use `nextSeq` to pull the group member list by page
{
...
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) {
// Messages failed to be pulled
}
@Override
public void onSuccess(V2TIMGroupMemberInfoResult groupMemberInfoResult) {
if (groupMemberInfoResult.getNextSeq() != 0) {
// Make another pull
getGroupMemberList(groupMemberInfoResult.getNextSeq());
...
} else {
// Pull ends
}
}
});
}
Call getGroupMembersInfo to get the profiles of group members in batches. You can pass in multiple userID
values at a time to improve network transmission efficiency.
The group owner or admin can call the setGroupMemberInfo API to modify the group-related information of members, including group name card (nameCard
), group member role (role
), muting duration (muteUntil
), and custom fields.
The group owner or admin can mute a group member and set muting duration (in seconds) via muteGroupMember. Muting information is stored in the muteUtil attribute field of the group member. After the group member is muted, all group members (including the muted member) receive the onMemberInfoChanged event 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 group muting. 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 an audio-video group (AVChatRoom) can have unlimited members, it does not support the API. You can use muteGroupMember to achieve the same effect instead.
After the member is removed, all group members (including the kicked member) receive the onMemberKicked callback.
The group owner can call setGroupMemberRole to change the role of a member of public group (Public) or meeting group (Meeting). Roles available for changing are common member and group admin.
The group owner can call transferGroupOwner to transfer the ownership of a group to other group members.
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.
A community group is a large group of people brought together by common topics, and multiple topics can be created under the same community group based on different interests.
Community groups are used to manage group members. All topics under the same community group share community members, and can send and receive messages independently without interfering with each other.
Note:Community group topics are supported only in 6.2.2363 and later versions.
You need to perform two steps to create a community group that supports topics:
groupType
to Community
and isSupportTopic
to true
in the object.Sample code:
V2TIMGroupInfo v2TIMGroupInfo = new V2TIMGroupInfo();
v2TIMGroupInfo.setGroupName("This is a Community");
v2TIMGroupInfo.setGroupType(V2TIMManager.GROUP_TYPE_COMMUNITY);
v2TIMGroupInfo.setSupportTopic(true);
V2TIMManager.getGroupManager().createGroup(v2TIMGroupInfo, null, new V2TIMValueCallback<String>() {
@Override
public void onSuccess(String groupID) {
// Community group created successfully
}
@Override
public void onError(int code, String desc) {
// Creation failed
}
});
Call the getJoinedCommunityList API to get the list of community groups the current user has joined.
Sample code:
V2TIMManager.getGroupManager().getJoinedCommunityList(new V2TIMValueCallback<List<V2TIMGroupInfo>>() {
@Override
public void onSuccess(List<V2TIMGroupInfo> v2TIMGroupInfos) {
// Community group list got successfully
}
@Override
public void onError(int code, String desc) {
// Failed to get the community group list
}
});
Other management APIs for the community groups and community group members are listed in the following table.
You need to perform two steps to create a topic:
Sample code:
V2TIMTopicInfo topicInfo = new V2TIMTopicInfo();
topicInfo.setTopicName(topicName);
topicInfo.setTopicFaceUrl(topicFaceUrl);
topicInfo.setIntroduction(topicIntroduction);
topicInfo.setNotification(topicNotification);
topicInfo.setCustomString(topicCustomString);
// Set `groupID` to the ID of a community group that supports topics
V2TIMManager.getGroupManager().createTopicInCommunity(groupID, topicInfo, new V2TIMValueCallback<String>() {
@Override
public void onSuccess(String topicID) {
// Topic created successfully
}
@Override
public void onError(int code, String desc) {
// Failed to create the topic
}
});
Call the deleteTopicFromCommunity API to delete a topic.
Sample code:
V2TIMManager.getGroupManager().deleteTopicFromCommunity(groupID, topicIDList, new V2TIMValueCallback<List<V2TIMTopicOperationResult>>() {
@Override
public void onSuccess(List<V2TIMTopicOperationResult> v2TIMTopicOperationResults) {
// Topic deleted successfully
}
@Override
public void onError(int code, String desc) {
// Failed to delete the topic
}
});
You need to perform two steps to modify the information of a topic:
Sample code:
V2TIMTopicInfo topicInfo = new V2TIMTopicInfo();
topicInfo.setTopicID(topicID);
topicInfo.setTopicName(topicName);
topicInfo.setTopicFaceUrl(topicFaceUrl);
topicInfo.setIntroduction(topicIntroduction);
topicInfo.setNotification(topicNotification);
topicInfo.setCustomString(topicCustomString);
topicInfo.setDraft(topicDraft);
topicInfo.setAllMute(false);
V2TIMManager.getGroupManager().setTopicInfo(topicInfo, new V2TIMCallback() {
@Override
public void onSuccess() {
// Topic information modified successfully
}
@Override
public void onError(int code, String desc) {
// Failed to modify the topic information
}
});
To modify other topic information, see Muting members and Modifying the topic message receiving option.
Call the getTopicInfoList API to get the list of topics.
topicIDList
is empty, the list of all topics of the community group will be got.topicIDList
is the ID of specified topics, the list of the specified topics will be got.Sample code:
V2TIMManager.getGroupManager().getTopicInfoList(groupID, topicIDList, new V2TIMValueCallback<List<V2TIMTopicInfoResult>>() {
@Override
public void onSuccess(List<V2TIMTopicInfoResult> v2TIMTopicInfoResults) {
// Topic list got successfully
}
@Override
public void onError(int code, String desc) {
// Failed to get the topic list
}
});
In V2TIMGroupListener, topic related callback methods onTopicCreated
, onTopicDeleted
, and onTopicInfoChanged
are added for topic event listening.
Sample code:
V2TIMGroupListener v2TIMGroupListener = new V2TIMGroupListener() {
@Override
public void onTopicCreated(String groupID, String topicID) {
// Listening for topic creation notifications
}
@Override
public void onTopicDeleted(String groupID, List<String> topicIDList) {
// Listening for topic deletion notifications
}
@Override
public void onTopicInfoChanged(String groupID, V2TIMTopicInfo topicInfo) {
// Listening for topic information update notifications
}
};
// Add an event listener for groups
V2TIMManager.getInstance().addGroupListener(v2TIMGroupListener);
Messages can be sent and received within a topic, and messages between different topics are independent of each other.
Topic message APIs are in the core class V2TIMMessageManager
and are described in the following table.
Feature | API | Description |
---|---|---|
Sending messages | sendMessage | Set `groupID` to the topic ID. |
Receiving messages | `onRecvNewMessage` method in V2TIMAdvancedMsgListener | Set `groupID` in the message to the topic ID. |
Marking messages as read | markGroupMessageAsRead | Set `groupID` to the topic ID. |
Getting the message history | getGroupHistoryMessageList | Set `groupID` to the topic ID. |
Recalling messages | revokeMessage | Set `groupID` to the topic ID. |
Yes, but since an audio-video group (AVChatRoom) does not support storing message history in the cloud, it cannot pull the messages that were sent when it was disconnected.
Meeting groups (Meeting) and audio-video groups (AVChatRoom) are designed for conference and live streaming scenarios respectively, and they do not support the unread count feature.
Was this page helpful?