Manage Chat Groups

Chat groups enable real-time messaging among multiple users.

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

Understand the tech

The Agora 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 Agora Chat SDK. For details, see Get Started with Android.
• You understand the call frequency limits of the Agora 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 Agora 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:

1. Call getPublicGroupsFromServer to retrieve the list of public groups by page. Users can obtain the ID of the group that they want to join.
2. 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

To retrieve the member list of a chat group, choose the method based on the group size:

• If the members of a chat group are greater than or equal to 200, list members of the chat group by page.
• If the members of a chat group are less than 200, call getGroupFromServer to retrieve the member list of the chat group.

Refer to the following sample code to retrieve the member list of a chat group:

// List members of a chat group by page.
List<String> memberList = new ArrayList<>;
CursorResult<String> result = null;
final int pageSize = 20;
do {
     result = ChatClient.getInstance().groupManager().fetchGroupMembers(groupId,
             result != null? result.getCursor(): "", pageSize);
     memberList.addAll(result.getData());
} while (!TextUtils.isnull(result.getCursor()) && result.getData().size() == pageSize);

// Call getGroupFromServer to retrieve the member list of a chat group.
Group group = ChatClient.getInstance().groupManager().getGroupFromServer(groupId, true);
List<String> memberList = group.getMembers();

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);