Manage chat groups

Chat groups enable real-time messaging among multiple users.

This page shows how to use the Chat SDK to create and manage a chat group in your app.

Understand the tech

The Chat SDK provides the Group, GroupManager, and GroupChangeListener classes for chat group management, which allows you to implement the following features:

Create and destroy a chat group
Join and leave a chat group
Retrieve the member list of a chat group
Block and unblock a chat group
Listen for the chat group events

Prerequisites

Before proceeding, ensure that you meet the following requirements:

You have initialized the Chat SDK. For details, see SDK quickstart.
You understand the call frequency limits of the Chat APIs supported by different pricing plans as described in Limitations.
You understand the number of chat groups and chat group members supported by different pricing plans as described in Pricing Plan Details.

Implementation

This section describes how to call the APIs provided by the Chat SDK to implement chat group features.

Create and destroy a chat group

Users can create a chat group and set the chat group attributes such as the name, description, group members, and reasons for creating the group. Users can also set the GroupOptions parameter to specify the size and type of the chat group. Once a chat group is created, the creator of the chat group automatically becomes the chat group owner.

Only chat group owners can disband chat groups. Once a chat group is disbanded, all members of that chat group receive the onGroupDestroyed callback and are immediately removed from the chat group. All local data for the chat group is also removed from the database and memory.

Refer to the following sample code to create and destroy a chat group:

GroupOptions option = new GroupOptions();
// Set the size of a chat group to 100 members.
option.maxUsers = 100;
// Set the type of a chat group to private. Allow chat group members to invite other users to join the chat group.
option.style = GroupStyle.GroupStylePrivateMemberCanInvite;
// Call createGroup to create a chat group.
ChatClient.getInstance().groupManager().createGroup(groupName, desc, allMembers, reason, option);
// Call destroyGroup to disband a chat group.
ChatClient.getInstance().groupManager().destroyGroup(groupId);

Join and leave a chat group

Users can request to join a public chat group as follows:

Call getPublicGroupsFromServer to retrieve the list of public groups by page. Users can obtain the ID of the group that they want to join.
Call joinGroup to send a join request to the chat group:
- If the type of the chat group is set to GroupStylePublicJoin, the request from the user is accepted automatically and the other chat group members receive the onMemberJoined callback.
- If the type of the chat group is set to GroupStylePublicNeedApproval, the chat group owner and chat group admins receive the onRequestToJoinReceived callback and determine whether to accept the request from the user.

Users can call leaveGroup to leave a chat group. Once a user leaves the group, all the other group members receive the onMemberExited callback.

Refer to the following sample code to join and leave a chat group:

// List public groups by page.
CursorResult<GroupInfo> result = ChatClient.getInstance().groupManager().getPublicGroupsFromServer(pageSize, cursor);
List<GroupInfo> groupsList = List<GroupInfo> returnGroups = result.getData();
String cursor = result.getCursor();
// Call joinGroup to send a join request to a chat group.
ChatClient.getInstance().groupManager().joinGroup(groupId);
// Call leaveGroup to leave a chat group.
ChatClient.getInstance().groupManager().leaveGroup(groupId);

Retrieve the member list of a chat group

When a group has less than 200 members, you can call the getGroupFromServer method to retrieve the group member list that contains the group owner, admins, and regular members.

// If `true` is passed to the second parameter, the SDK returns the group member list that contains up to 200 group members.
// It is a synchronous method and may block the current thread.
Group group = ChatClient.getInstance().groupManager().getGroupFromServer(groupId, true);
List<String> memberList = group.getMembers();// gets regular members.
memberList.addAll(group.getAdminList());// gets group admins.
memberList.add(group.getOwner());// gets the group owner.

When a group has more than 200 members, you can first call the getGroupFromServer method to get the group member list that contains the group owner and admins and then call the fetchGroupMembers method to obtain the list of regular group members.

// If `true` is passed to the second parameter, the SDK returns the group member list that contains up to 200 group members.
// It is a synchronous method and may block the current thread.
Group group = ChatClient.getInstance().groupManager().getGroupFromServer(groupId, true);
List<String> memberList = new ArrayList<>();
CursorResult<String> result = null;
final int pageSize = 20;
do {
    // It is a synchronous method and may block the current thread. The asynchronous method is asyncFetchGroupMembers(String, String, int, ValueCallBack).
     result = ChatClient.getInstance().groupManager().fetchGroupMembers(groupId,
             result != null? result.getCursor(): "", pageSize);
     memberList.addAll(result.getData());
} while (!TextUtils.isEmpty(result.getCursor()) && result.getData().size() == pageSize);
 memberList.addAll(group.getAdminList());// gets group admins.
 memberList.add(group.getOwner());// gets the group owner.

Block and unblock a chat group

All chat group members can block and unblock a chat group. Once a member block a chat group, they no longer receive messages from this chat group.

Refer to the following sample code to block and unblock a chat group:

// Call blockGroupMessage to block a chat group.
ChatClient.getInstance().groupManager().blockGroupMessage(groupId);
// Call unblockGroupMessage to unblock a chat group.
ChatClient.getInstance().groupManager().unblockGroupMessage(groupId);

Listen for chat group events

To monitor the chat group events, users can listen for the callbacks in the GroupManager class and add app logics accordingly. If a user wants to stop listening for the callbacks, make sure that the user removes the listener to prevent memory leakage.

Refer to the following sample code to listen for chat group events:

GroupChangeListener groupListener = new GroupChangeListener() { 
    // Occurs when an invitee receives a group invitation.
    @Override
    public void onInvitationReceived(String groupId, String groupName, String inviter, String reason) {
        
    }
    // Occurs when a user sends a join request to a chat group.
    @Override
    public void onRequestToJoinReceived(String groupId, String groupName, String applyer, String reason) {
        
    }
    // Occurs when the chat group owner or admin approves a join request.
    @Override
    public void onRequestToJoinAccepted(String groupId, String groupName, String accepter) {
        
    }
    // Occurs when the chat group owner or admin rejects a join request.
    @Override
    public void onRequestToJoinDeclined(String groupId, String groupName, String decliner, String reason) {
        
    }
    // Occurs when an invitee accepts a group invitation.
    @Override
    public void onInvitationAccepted(String groupId, String inviter, String reason) {
        
    }
    // Occurs when an invitee declines a group invitation.
    @Override
    public void onInvitationDeclined(String groupId, String invitee, String reason) {
        
    }
    // Occurs when a member is removed from a chat group.
    @Override
    public void onUserRemoved(String groupId, String groupName) {
        
    }
    // Occurs when the chat group owner disbands a chat group.
    @Override
    public void onGroupDestroyed(String groupId, String groupName) {
    }
    // Occurs when an invitee accepts a group invitation automatically.   
    @Override
    public void onAutoAcceptInvitationFromGroup(String groupId, String inviter, String inviteMessage) {
        
    }
    // Occurs when a member is added to the chat group mute list.
    @Override
    public void onMuteListAdded(String groupId, final List<String> mutes, final long muteExpire) {
        
    }
    // Occurs when a member is removed from the chat group mute list.
    @Override
    public void onMuteListRemoved(String groupId, final List<String> mutes) {
        
    }
    // Occurs when a member is added to the chat group allow list.
    @Override
    public void onWhiteListAdded(String groupId, List<String> whitelist) {
          
    }
    // Occurs when a member is removed from the chat group allow list.
    @Override
    public void onWhiteListRemoved(String groupId, List<String> whitelist) {
         
    }
    // Occurs when all chat group members are muted or unmuted.
    @Override
    public void onAllMemberMuteStateChanged(String groupId, boolean isMuted) {
          
    }
    // Occurs when a member is added to the chat group admin list.
    @Override
    public void onAdminAdded(String groupId, String administrator) {
        
    }
    // Occurs when an admin is removed from the chat group admin list.
    @Override
    public void onAdminRemoved(String groupId, String administrator) {
        
    }
    // Occurs when the chat group owner is changed.
    @Override
    public void onOwnerChanged(String groupId, String newOwner, String oldOwner) {
        
    }
    // Occurs when a user joins a chat group.
    @Override
    public void onMemberJoined(final String groupId, final String member){
        
    }
    // Occurs when a member leaves a chat group.
    @Override
    public void onMemberExited(final String groupId, final String member) {
        
    }
    // Occurs when a member updates the chat group announcement.
    @Override
    public void onAnnouncementChanged(String groupId, String announcement) {
        
    }
    // Occurs when a member uploads a chat group shared file.
    @Override
    public void onSharedFileAdded(String groupId, MucSharedFile sharedFile) {
        
    }
    // Occurs when a member deletes a chat group shared file.
    @Override
    public void onSharedFileDeleted(String groupId, String fileId) {
        
    }
};
// Add the group listener.
ChatClient.getInstance().groupManager().addGroupChangeListener(groupListener);
// Remove the group listener if not use.
ChatClient.getInstance().groupManager().removeGroupChangeListener(groupListener);

You are viewing Agora Docs forBetaproducts and features. Switch to Docs