Chat group overview

Chat groups are features that enable instant messaging among multiple chat users. The relationship between chat group members is persistent: chat group members can send and receive messages in the group and also receive push messages when they are offline.

Groups can be divided into public groups and private groups according to the public accessibility.

Group type	Join method	Retrieval of group information
Public group	Any users can apply to join a group or be invited by the group owner or an admin to join. Whether the join requests need to be approved by the group owner or admins depends on the group setting, for example, GroupStyle for Android.	The specifications of a group and the list of public groups are accessible to the public. The group announcement, the list of group shared files, and the group member list are only accessible to users that have joined the group.
Private group	Users can only be invited to join a group. Whether regular group members, besides the group owner and admins, can invite a user to join the group depends on the group setting, for example, GroupStyle for Android.	The group specifications, group announcement, the list of group shared files, and the group member list are only accessible to users that have joined the group.

The offline push function is not available to group with more than 3000 members. To enable the offline push function for such a large group, contact support@agoro.io before creating it. Note that it is impossible to enable the offline push function for a large group that is created. The maximum number of members that a group can contain varies with your price plans. For details, see Pricing Plan Details.

Chat groups have the following roles and privileges:

• Chat group members: Members can send and receive group messages. They do not have any administrative privileges.
• Chat group admins: Admins are members that also have some administrative privileges, including modifying the group announcements and managing chat group members (but not other admins). Admins are appointed by the chat group owner.
• Chat group owner: The owner is the group member with the most authority. When a user creates a chat group, they automatically become the group owner. Owners have the most privileges in a chat group, including appointing group admins, modifying group announcements, and managing group members (including admins). Owners can also disband the group or transfer ownership to another member.

Chat groups and chat rooms both support instant messaging among multiple users. However, chat groups typically have a more consistent membership then Chat rooms. Chat group users are normally connected to the group itself; chat room users are more likely to be connected by their interest in the subject of the chat room, and so they tend to join and leave more freely.

The specific feature differences are listed in the following table:

Feature	Chat group	Chat room
Use cases	Group chat scenarios in Signal and Skype, where members have a preexisting relationship with each other.	Stream chat scenarios in Twitch, where viewers have no relationship with each other. Once a member quits the stream channel, they leave the chat room.
Maximum number of members	5,000	20,000+
Message push support	Members receive push messages when they go offline.	Members do not receive push messages when they go offline.
Offline message storage	This feature is supported. Agora Chat servers store messages sent to offline group members and sends to them once they go back online. A maximum number of 200 messages across chat groups can be stored per end user.	Chat room does not store messages sent to offline chat room members and this feature is not supported in chat rooms.
Message history	Agora Chat servers store message history, subject to the data retention period of your package selection. The history can be retrieved by your app server via this RESTful API, in the format of JSON files. You can call this Client API to allow the SDK to retrieve message history of a chat group. This allows end users to synchronize messages history across multiple end devices.	Agora Chat servers store message history, subject to the data retention period of your package selection. The history can be retrieved by your app server via this RESTful API, in the format of JSON files. Agora Chat currently does not support SDK retrieving message history of a chat room via client APIs. However, when a user joins a chat room, Agora Chat servers can send 10 most recent messages to the client side via the message receiving callback. To enable this function, you need to contact support@agora.io. The number of historical messages sent to the new chat room member can be increased up to 200, without additional charges.
Message reliability	Each member receives all the messages in the chat group.	Members might not see all messages. The SDK discards messages if the chat room message threshold is exceeded. The default threshold is 100 messages per second. You can adjust this threshold according to your needs.

The Chat SDK supports creating and managing chat groups, managing group members, and modifying group attributes.

You can implement the following features with the chat group APIs.

Any chat user can create a chat group. A user that creates a chat group becomes its owner. The maximum number of chat groups and group members supported varies accroding to the pricing plan. For details, see Chat group total member limits.

Users can search for public chat groups and request to join them by the group ID. For private chat groups, you can only join the group if the group owner or admin sends you a group chat invitation.

Chat group members and admins can quit a chat group. Once they do, they no longer receive the group messages. Group owners cannot quit the chat group; instead, they must transfer ownship or disband the chat group. When a chat group is disbanded, all of its members are forced to leave the group.

Owners and admins for both public and private chat groups can invite other users to join their group.

Chat group owners and admins can remove a specified member from their group.

Only the group owner can disband a chat group. Once a chat group is disbanded, all local group data is deleted, and all the group members are forced to leave the group.

All the chat group users can retrieve a paginated list of the group's membership from the server. The members are displayed in descending order according to the timestamp when they joined the chat group.

Users can retrieve the list of groups they have created or joined.

All chat group members can block and unblock group messages. Once a user blocks group messages, the user no longer receive messages from the specified chat group.

You can listen for chat group events such as when a user joins and leaves the group, and add app logic as needed.

Group owners or admins can add a specified group members to the block list; they can also remove blocked users from the list. Members added to the block list are forced to leave the chat group and can no longer join it.

Group owners and admins can retrieve the chat group block list. Members on the group block list cannot join the chat group.

Chat group owners and admins can add specified group members to the group allow list; they can also remove users from the list. Members on the allow list can send group messages when a group owner or an admin has muted all group members.

Chat group owners and admins can retrieve the chat group allow list. Members on the group allow list can still send group messages when a chat group owner or admin has muted all the group members.

Chat group owner or admin can add specifed group members to the group mute list. They can also remove them from list. Members on the mute list can no longer send chat group messages. Muted members still receive group messages.

Chat group owners and admins can mute or unmute all the chat group members simultaneously. Muting all members prevents anyone from sending group messages except the group owner, admins, and the group members on the group allow list. Muted members still receive group messages.

Chat group owners and admins can retrieve the chat group mute list. Members in the group mute list cannot send group messages.

A chat group owner can transfer ownership of the group to a specified group member. Once the ownership is transferred, the group owner becomes a regular group member.

Chat group owners can add members to the chat group admin list; they can also remove them from the list. Members on the admin list gain all admin privileges.

Chat group owners and admins can modify their chat group name and description. They can also set or update the group announcements. Chat group members can retrieve group announcements.

All the chat group members can upload or download group shared files. Chat group owners and admins can delete all group shared files, whereas group members can only delete shared files whey have personally uploaded.

Chat group owners and admins can update the extension information of the chat group. Extension information can be used to customize group extensions. The data length of the extension information cannot exceed 8 KB.

The maximum number of members per chat group depends on your pricing plan, as follows: 100 for Free, 10,000 for Starter, 50,000 for Pro, and custom (100,000 by default) for Enterprise.