Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Manage chat group attributes

Updated

Introduces how to use the Agora Chat SDK to manage the attributes of a chat group in your app.

Chat groups enable real-time messaging among multiple users.

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

Understand the tech

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

  • Modify the chat group name and description
  • Manage chat group announcements
  • Manage chat group shared files

Prerequisites

Before proceeding, ensure that you meet the following requirements:

  • You have initialized the Chat SDK. For details, 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.

Modify the chat group name and description

The chat group owner and chat group admins can modify the name and description of the chat group.

Refer to the following sample code to modify the chat group name and description:

// The chat group owner and chat group admins can call modifyGroup to modify the name and description of a chat group.
// The name length can be up to 128 characters. The description length can be up to 512 characters.
const options = {
  groupId: "groupId",
  groupName: "groupName",
  description: "A description of group",
};
chatClient.modifyGroup(options).then((res) => console.log(res));

Update the chat group avatar

Since SDK v1.4.0, you can set, update, and retrieve the chat group avatar.

You can set the group avatar when you create the group by passing the avatar parameter to createGroupVNext. For details, see Create and destroy a chat group.

After the group is created, the chat group owner and admins can call modifyGroup to set or update the avatar:

const options = {
  groupId: "groupId",
  avatar: "group avatar url",
};
chatClient.modifyGroup(options).then((res) => console.log(res));

Once the avatar is changed, all the other chat group members receive the group event with the updateInfo operation:

chatClient.addEventHandler("handlerId", {
  onGroupEvent: function (msg) {
    switch (msg.operation) {
      case "updateInfo":
        console.log(msg);
        break;
    }
  },
});

All chat group members can retrieve the group avatar from the group details returned by getGroupInfo:

chatClient.getGroupInfo({ groupId: "groupId" }).then((res) => {
  console.log(res);
});

Manage chat group announcements

The chat group owner and chat group admins can set and update chat group announcements. Once the announcements are updated, all chat group members receive the updateAnnouncement callback. All chat group members can retrieve chat group announcements.

Refer to the following sample code to manage chat group announcements:

// The chat group owner and chat group admins can call updateGroupAnnouncement to set or update the chat group announcements.
// The announcement length can be up to 512 characters.
const options = {
  groupId: "groupId",
  announcement: "A announcement of group",
};
chatClient.updateGroupAnnouncement(options).then((res) => console.log(res));

// All chat group members can call fetchGroupAnnouncement to retrieve the chat group announcements.
const options = {
  groupId: "groupId",
};
chatClient.fetchGroupAnnouncement(options).then((res) => console.log(res));

Manage chat group shared files

All chat group members can upload or download group shared files. The chat group owner and chat group admins can delete all of the group shared files, whereas group members can only delete the shared files that they have personally uploaded.

Refer to the following sample code to manage chat group shared files:

// All chat group members can call uploadGroupSharedFile to upload group shared files. The file size can be up to 10 MB.
// Once shared files are uploaded, group members receive the uploadFile callback.
const options = {
  groupId: "groupId",
  file: file, // Choose the file to upload and share.
  onFileUploadProgress: function (resp) {}, // The callback of the upload progress
  onFileUploadComplete: function (resp) {}, // The callback of the upload success
  onFileUploadError: function (e) {}, // The callback of the upload failure
  onFileUploadCanceled: function (e) {}, // The callback of the upload cancelation
};
chatClient.uploadGroupSharedFile(options);

// All chat group members can call downloadGroupSharedFile to delete group shared files.
const options = {
  groupId: "groupId",
  fileId: "fileId", // The ID of the file
  onFileDownloadComplete: function (resp) {}, // The callback of the upload success
  onFileDownloadError: function (e) {}, // The callback of the upload failure
};
chatClient.downloadGroupSharedFile(options);

// All chat group members can call deleteGroupSharedFile to delete group shared files.
const options = {
  groupId: "groupId",
  fileId: "fileId", // The ID of the file
};
chatClient.deleteGroupSharedFile(options).then((res) => console.log(res));

// All chat group members can call getGroupSharedFilelist to retrieve the list of shared files in the chat group.
const options = {
  groupId: "groupId",
};
chatClient.getGroupSharedFilelist(options).then((res) => console.log(res));

Listen for chat group events

For details, see Chat Group Events.

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved