Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

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:


_12
GroupOptions option = new GroupOptions();
_12
// Set the size of a chat group to 100 members.
_12
option.maxUsers = 100;
_12
// Set the type of a chat group to private. Allow chat group members to invite other users to join the chat group.
_12
option.style = GroupStyle.GroupStylePrivateMemberCanInvite;
_12
_12
// Call createGroup to create a chat group.
_12
ChatClient.getInstance().groupManager().createGroup(groupName, desc, allMembers, reason, option);
_12
_12
_12
// Call destroyGroup to disband a chat group.
_12
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:


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

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

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


_5
// Call blockGroupMessage to block a chat group.
_5
ChatClient.getInstance().groupManager().blockGroupMessage(groupId);
_5
_5
// Call unblockGroupMessage to unblock a chat group.
_5
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:


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

vundefined