logo
In-app Chat
SDK Error Codes
Powered Byspreading
On this page

Manage groups


ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of group management, allowing you to create a group, ungroup, join and leave a group, and maintain the group relation chain.

With the group management feature, you can create different types of group chats as needed, such as colleague groups, social groups, fan groups, and more.

Create a group

After user A logs in to the ZIM SDK on a client, the user can call the createGroup method to create a group with advanced settings. In this case, user A logged on this client is the group owner, and users on other clients can join this group using the groupID.

You can check whether the group is created through the ZIMGroupCreatedCallback callback. For more information about error codes, see Error codes.

Warning
  • You can specify custom rules for groupID generation. A group ID can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~', and cannot start with a pound sign (#). If this parameter is empty, the ZIM server automatically generates a value. We recommend that you set a meaningful group ID generation rule. You can associate the group ID with your business account system.
  • If a user calls the createGroup method to create a group, the user automatically joins the group without calling the joinGroup method.
  • The user creating a group is the group owner. For more information about group ownership transfer, see Transfer the group ownership.
  • To specify the maximum number of group members and the group joining mode (including the approval mode, invitation mode, and whether the invitation needs to be approved by the invitee), integrate ZIM SDK 2.15.0 or later.
Untitled
// Create a group.
// The groupID parameter can contain up to 32 bytes in length, including digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'. It cannot start with a pound sign (#).
// The groupName parameter can contain up to 50 bytes in length, with no limit on characters.
ZIMGroupInfo groupInfo = new ZIMGroupInfo();
groupInfo.groupID = "group_id";
groupInfo.groupName = "groupName";
groupInfo.groupAvatarUrl = "groupAvatarUrl";

ZIMGroupAdvancedConfig config = new ZIMGroupAdvancedConfig();
HashMap<String, String> attributes = new HashMap<>();
attributes.put("key_0", "value_0");
attributes.put("key_1", "value_1");
attributes.put("key_2", "value_2");
config.groupAttributes = attributes;
// // The mode where a user sends a group joining application.
config.joinMode = ZIMGroupJoinMode.ANY;
// The mode where a group member invites a user to a group.
config.inviteMode = ZIMGroupInviteMode.ANY;
// The mode where a user is invited to a group.
config.beInviteMode = ZIMGroupBeInviteMode.NONE;
// The maximum number of members in the group.
config.maxMemberCount = 300;

ArrayList<String> userList = new ArrayList<>();
userList.add("user_1");
userList.add("user_2");

zim.createGroup(groupInfo, userList, config, new ZIMGroupCreatedCallback() {
    @Override
    public void onGroupCreated(ZIMGroupFullInfo groupInfo, ArrayList<ZIMGroupMemberInfo> userIDs, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // Get the result of creating a group through errorInfo.code
    }
});
1
Copied!

Join a group

Note

If you want users to automatically obtain group history messages after joining a group, please contact the ZEGOCLOUD technical support team for configuration.

After logging in to the ZIM SDK, users can apply to join or be invited to join a group created by user A.

If a user successfully joins the group, all group members (including the user) receive the onGroupMemberStateChanged and onGroupStateChanged callbacks.

Untitled
//    Listen for onGroupMemberStateChanged and onGroupStateChanged
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupMemberStateChanged(ZIM zim, ZIMGroupMemberState state, ZIMGroupMemberEvent event, ArrayList<ZIMGroupMemberInfo> userList, ZIMGroupOperatedInfo operatedInfo, String groupID) {
          // Callback notification of group member status change.
    }

    public void onGroupStateChanged(ZIM zim, ZIMGroupState state, ZIMGroupEvent event, ZIMGroupOperatedInfo operatedInfo, ZIMGroupFullInfo groupInfo) {
          // Callback notification of group status change.
    }

});
1
Copied!

Method 1: Apply to join a group

The user calls the corresponding method to apply to join a group based on the joinMode of the group.

  • If the joinMode is set to 0 (ANY), the user calls the joinGroup method and passes in the groupID to join the group without approval. If the groupID does not exist, the operation fails.
Untitled
// Join the group on another client.
zim.joinGroup("groupID", new ZIMGroupJoinedCallback() {
    @Override
    public void onGroupJoined(ZIMGroupFullInfo groupInfo, ZIMError errorInfo) {
        //Get the result of joining the group through errorInfo.code.
    }
});
1
Copied!
  • If the joinMode is set to 1 (AUTH):
  1. The user calls the sendGroupJoinApplication method to send an application.
Untitled
ZIMGroupJoinApplicationSendConfig config = new ZIMGroupJoinApplicationSendConfig();
config.wording = @"Let me join the group.";
zim.sendGroupJoinApplication("groupID", config, new ZIMGroupJoinApplicationSentCallback() {
    @Override
    public void onGroupJoinApplicationSent(String groupID, ZIMError errorInfo){     
      // The callback for sending the group joining application.     
}];
1
Copied!
  1. The group owner or administrator receives the application notification by listening for the onGroupApplicationListChanged event.
Untitled
// Listen for groupApplicationListChanged event.
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupApplicationListChanged(ZIM zim, ArrayList<ZIMGroupApplicationInfo> applicationList, ZIMGroupApplicationListChangeAction action) {
    // Group application list update callback notification.  
    }
});
1
Copied!
  1. The group owner or administrator handles the application.
Untitled
// Approve the application.
ZIMGroupJoinApplicationAcceptConfig config = new ZIMGroupJoinApplicationAcceptConfig();
zim.acceptGroupJoinApplication("userID", "groupID", config, new ZIMGroupJoinApplicationAcceptedCallback(){
    public void onGroupJoinApplicationAccepted(String groupID, String userID, ZIMError errorInfo){
        // The callback for application approval.
}];
1
Copied!
Untitled
// Reject the application.
ZIMGroupJoinApplicationRejectConfig config = new ZIMGroupJoinApplicationRejectConfig();
zim.rejectGroupJoinApplication("userID", "groupID", config, new ZIMGroupJoinApplicationRejectedCallback(){
    public void onGroupJoinApplicationRejected(String groupID, String userID, ZIMError errorInfo) {                // The callback for application rejection.
}];
1
Copied!
  1. The user applying to join the group, the group owner or administrator, and the method caller receive the onGroupApplicationUpdated callback.
Untitled
// Listen for onGroupApplicationUpdated event.
zim.setEventHandler(new ZIMEventHandler(){
        public void onGroupApplicationUpdated(ZIM zim, ArrayList<ZIMGroupApplicationInfo> applicationList){
        //  Group application information update callback.
        }
});
1
Copied!

Method 2: Invite a user to a group

  1. A group member can invite a user to the group by calling one of the following methods.
Warning

Make sure that the invitee has been registered by calling the login method; otherwise, the operation fails.

Untitled
// A group member invites a user to the group.
ArrayList<String> userList = new ArrayList<>();
userList.add("user_1");
userList.add("user_2");
zim.inviteUsersIntoGroup(userList, "group_id", new ZIMGroupUsersInvitedCallback() {
    @Override
    public void onGroupUsersInvited(ArrayList<ZIMGroupMemberInfo> userList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // Get the result of adding to the group through errorInfo.code.  
    }
});
1
Copied!
Untitled
// Send the group invitation.
ZIMGroupInviteApplicationSendConfig config = new ZIMGroupInviteApplicationSendConfig();
config.wording = @"xxx invited you to join the group.";
List<String> userIDs = new ArrList<String>();
userIDs.add("user1");
userIDs.add("user2");
zim.sendGroupInviteApplications(userIDs, "groupID", config, new ZIMGroupInviteApplicationsSentCallback(){
    public void onGroupInviteApplicationsSent(String groupID, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo){
        // Initiate group invitation result callback.
    }
});
1
Copied!

The following table describes the operation results of different methods called by different roles in a group in inviteMode and beInviteMode modes.

beInviteModeinviteModeMethodCallerResult
0: None0: AnyinviteUsersIntoGroupAll group membersThe invitee joins the group without approval.
sendGroupInviteApplicationsToUserIDsThe invitee joins the group without approval, with no application generated.
1: AdmininviteUsersIntoGroupOrdinary membersFailed.
Group owner or administratorThe invitee joins the group without approval.
sendGroupInviteApplicationsToUserIDsOrdinary membersFailed.
Group owner or administratorThe invitee joins the group without approval, with no application generated.
1: Auth0: AnyinviteUsersIntoGroupAll group membersAn application is generated and sent to the invitee for approval.
sendGroupInviteApplicationsToUserIDsAn application is generated and sent to the invitee for approval. If the caller is the group owner or administrator, the groupApplicationListChanged callback is generated.
1: AdmininviteUsersIntoGroupOrdinary membersFailed.
Group owner or administratorAn application is generated and sent to the invitee for approval.
sendGrsendGroupInviteApplicationsToUserIDsoupInviteApplicationsOrdinary membersFailed.
Group owner or administratorAn application is generated and sent to the invitee for approval. If the caller is the group owner or administrator, the groupApplicationListChanged callback is generated.
  1. If the beInviteMode is set to 1 (AUTH), the invitee and inviter (the group owner or administrator) receive the notification in the onGroupApplicationListChanged callback. The invitee can perform the following operations on the application:
Untitled
// Agree to join the group invitation.
ZIMGroupInviteApplicationAcceptConfig config = new ZIMGroupInviteApplicationAcceptConfig();
zim.acceptGroupInviteApplication("inviterUserID", "groupID", config, new ZIMGroupInviteApplicationAcceptedCallback(){

    public void onGroupInviteApplicationAccepted(ZIMGroupFullInfo groupInfo, String inviterUserID, ZIMError errorInfo){
        // Callback for agree group invitation result.
    }
});
1
Copied!
Untitled
// Refuse to join the group invitation. 
ZIMGroupInviteApplicationRejectConfig config = new ZIMGroupInviteApplicationRejectConfig();
zim.rejectGroupInviteApplication("inviterUserID", "groupID", config, new ZIMGroupInviteApplicationRejectedCallback(){
    public void onGroupInviteApplicationRejected(String groupID, String inviterUserID, ZIMError errorInfo) {
            //  Reject group invitation result callback.
    }
});
1
Copied!
  1. If the beInviteMode is set to 1 (AUTH), the invitee and inviter (the group owner or administrator) receive the approval notification in the onGroupApplicationUpdated callback.
Untitled
zim.setEventHandler(new ZIMEventHandler(){
  public void onGroupApplicationUpdated(ZIM zim,
                                      ArrayList<ZIMGroupApplicationInfo> applicationList) {
          // Group application update callback notification.         }
});
1
Copied!

Leave a group

A group member can leave a group or be removed from a group.

Warning

After a group member leaves a group, the local list of conversations is retained, and historical group messages can be viewed.

Method 1: A group member leaves the group

After logging in to the ZIM SDK, the group member calls the leaveGroup method and passes in the groupID. If the groupID does not exist, the operation fails. After the group member leaves the group, all group members receive the onGroupMemberStateChanged callback.

Note

If the group owner leaves the group, the group ownership is automatically transferred to the first group member. If all group members leave the group, the group is automatically disbanded.

Untitled
// Leave a group.
zim.leaveGroup("groupID", new ZIMGroupLeftCallback() {
    @Override
    public void onGroupLeft(ZIMError errorInfo) {
        // Get the result of actively exiting the group through errorInfo.code. 
    }
});
1
Copied!

Method 2: The group owner removes a group member from the group

The group owner calls the kickGroupMembers method and passes in the groupID and userIDList (list of users to be removed). If the groupID does not exist, the operation fails. After one or more group members are removed, all group members (including the group owner and the removed group members) receive the onGroupMemberStateChanged callback.

Warning
  • Only the group owner or administrator can call the kickGroupMembers method to remove a group member, who does not need to be logged in or approve the removal.
  • The userID of the user to be removed must be in the list of group members; otherwise, the operation fails.
Untitled
// The group owner removes one or more group members from the group.
ArrayList<String> user_list = new ArrayList<>();
user_list.add("user_1");
user_list.add("user_2");
zim.kickGroupMembers(user_list, "groupID", new ZIMGroupMemberKickedCallback() {
    @Override
    public void onGroupMemberKicked(ArrayList<String> kickedUserIDList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
        // Get the result of actively exiting the group through errorInfo.code.   
    }
});
1
Copied!

Disband a group

After logging in to the ZIM SDK, the group owner calls the dismissGroup method to disband a group. After the group is disbanded, all group members receive the onGroupStateChanged callback.

Note
  • Only the group owner can call the dismissGroup method to disband a group.
  • If all group members leave a group, the group is automatically disbanded.
  • After a group is disbanded, the local list of conversations is retained, and historical messages can be viewed.
Untitled
// The group owner disbands the group.
zim.dismissGroup("groupID", new ZIMGroupDismissedCallback() {
    @Override
    public void onGroupDismissed(ZIMError errorInfo) {
        // Get the result of actively exiting the group through errorInfo.code.
    }
});
1
Copied!

More features

Query the list of joined groups

After logging in to the ZIM SDK, a user calls the queryGroupList method to query the list of joined groups.

Untitled
// The user queries the list of joined groups.
zim.queryGroupList(new ZIMGroupListQueriedCallback() {
    @Override
    public void onGroupListQueried(ArrayList<ZIMGroupInfo> groupList, ZIMError errorInfo) {
        // Get the result of actively exiting the group through errorInfo.code.
    }
});
1
Copied!

Search for joined groups

After logging in to the ZIM SDK, a user calls the searchLocalGroups method and passes in the config and callback parameters to search for joined groups by condition.

The search result is returned in the ZIMGroupsSearchedCallback callback.

Untitled
// Search for joined groups that contain a member named "zego".
ZIM zim = getZIM();
ZIMGroupMemberSearchConfig config = new ZIMGroupMemberSearchConfig();
config.count = 10;
config.nextFlag = 0;
config.isAlsoMatchGroupMemberNickname = true; //  If the nickname of a group member contains "zego", the group is returned in the search result.
config.isAlsoMatchGroupMemberUserName = true; // If the username of a group member contains "zego", the group is returned in the search result.
config.keywords.add("zego");
zim.searchLocalGroups(config, new ZIMGroupsSearchedCallback() {
    @Override
    public void onGroupsSearched(ArrayList<ZIMGroupSearchInfo> groupSearchInfoList, int nextFlag, ZIMError errorInfo) {
        // You can obtain the group information in the groupSearchInfoList field.
    }
});
1
Copied!

Mute or unmute a group

If a group is muted, group members cannot send messages to the group.

After logging in to the ZIM SDK, a user can mute or unmute a group on which the user has management permission by calling the muteGroup method and passing in parameters to specify the group ID, mute mode, duration, and role.

The ZIM SDK supports three mute modes:

  • All group members are muted.
  • All ordinary group members (whose role value is 3) are muted.
  • Group members of specified roles are muted.

The result is returned in the ZIMGroupMutedCallback callback.

Note

If you want to block specific group members from posting, please refer to Set mute status for group members - Manage group members.

Untitled
// Configure group muting.
ZIMGroupMuteConfig config = new ZIMGroupMuteConfig();
// Group members of specified roles are muted.
config.mode = ZIMGroupMuteMode.Custom;
// These members are muted for 30 seconds.
config.duration = 30;
// Group members whose `role` value is `3` or `5` are muted.
config.roles.add(3);
config.roles.add(5);


// Enable muting
boolean isMute = true;

zim.muteGroup(isMute, "group_id", config, new ZIMGroupMutedCallback() {
     @Override
     public void onGroupMuted(String groupID, boolean isMute, ZIMGroupMuteInfo info, ZIMError errorInfo) {
                
     }
});

1
Copied!

After a group is muted or unmuted, all group members receive the onGroupMutedInfoUpdated callback and know which roles are muted or unmuted.

Untitled
zim.setEventHandler(new ZIMEventHandler(){

    public void onGroupMutedInfoUpdated(ZIM zim, ZIMGroupMuteInfo muteInfo,
                                       ZIMGroupOperatedInfo operatedInfo, String groupID) {
    // Listen for the group muting status change and handle the change by inheriting the ZIMEventHandler method.
   }
});
1
Copied!

Check whether a user is in a group

To check whether a user is in a group, call any of the following methods:

For group chats, the result is indicated by the isDisabled property of ZIMGroupConversation.

Valid values of isDisabled:

  • true: The user is not in the group. If the user leaves the group or is removed from the group, or the group is disbanded, the value of isDisabled is false.
  • false: The user is in the group.

Update the group joining mode

After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupJoinMode method to update the group joining mode.

After the mode is updated, all group members receive the onGroupVerifyInfoUpdated callback.

Untitled
// Listen for onGroupVerifyInfoUpdated event.
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // Update joinMode of a group.
     }

   });

// Update the verification mode for others to join the group
zim.updateGroupJoinMode(ZIMGroupJoinMode.AUTH, "groupID", new ZIMGroupJoinModeUpdatedCallback(){
public void onGroupJoinModeUpdated(String groupID, ZIMGroupJoinMode mode, ZIMError errorInfo){
// Update verification mode result callback notification
}
});
1
Copied!

Update inviteMode of a group

After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupInviteMode method to update inviteMode of the group.

After the mode is updated, all group members receive the onGroupVerifyInfoUpdated callback.

Untitled
// Listen for onGroupVerifyInfoUpdated event.
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // Invite mode update callback notification.
     }

   });

// Updated verification mode for inviting others to join the group.
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // Update inviteMode of the group.
     }

   });
1
Copied!

Update beInviteMode

After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupBeInviteMode method to update beInviteMode.

After the mode is updated, all group members receive the onGroupVerifyInfoUpdated callback.

Untitled
// Listen for onGroupVerifyInfoUpdated event.
zim.setEventHandler(new ZIMEventHandler(){
    public void onGroupVerifyInfoUpdated(ZIM zim, ZIMGroupVerifyInfo verifyInfo,
                                         ZIMGroupOperatedInfo operatedInfo, String groupID) {
        // Invite mode update callback notification.
     }

   });


// Update beInviteMode.
zim.updateGroupInviteMode(ZIMGroupInviteMode.ADMIN, "groupID", new ZIMGroupInviteModeUpdatedCallback(){
    public void onGroupInviteModeUpdated(String groupID, ZIMGroupInviteMode mode, ZIMError errorInfo){
        // Update the callback notification of the verification mode result of inviting others to join the group.
    }
});
1
Copied!

Query the list of group joining applications

After logging in to the ZIM SDK, a user calls the queryGroupApplicationList method to query the list of group joining applications. The query result contains applications sent to the user.from and to the user.

Untitled

ZIMGroupApplicationListQueryConfig config = new ZIMGroupApplicationListQueryConfig();
config.count = 10;
// Fill in 0 for the first query.
conifg.nextFlag = 0; 
zim.queryGroupApplicationList(config,  new ZIMGroupApplicationListQueriedCallback() {
     public void onGroupApplicationListQueried(ArrayList<ZIMGroupApplicationInfo> applicationList, int nextFlag, ZIMError errorInfo) {
            // Query group application list result callback.
     }
})
1
Copied!

Previous

Manage room user attributes

Next

Manage group info