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

Manage chat groups

Updated

Introduces chat group functionalities.

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 allows you to implement the following group management features:

  • Create and destroy a chat group
  • Join and leave a chat group
  • Retrieve the member list of 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 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 destroy 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:

const options = {
  data: {
    groupname: "groupName",
    desc: "A description of a group",
    members: ["user1", "user2"],
    // Set the type of a chat group to public. Public chat groups can be searched, and users can send join requests.
    public: true,
    // Join requests must be approved by the chat group owner or chat group admins.
    approval: true,
    // Allow chat group members to invite other users to join the chat group.
    allowinvites: true,
    // Group invitations must be confirmed by invitees.
    inviteNeedConfirm: true,
    // Set the maximum number of users that can be added to the group.
    maxusers: 500,
  },
};
// Call createGroup to create a chat group.
chatClient.createGroup({ data: options });

// Call destroyGroup to disband a chat group.
const options = {
  groupId: "groupId",
};
chatClient.destroyGroup(options).then((res) => console.log(res));

Since SDK v1.4.0, call createGroupVNext to create a chat group and set its attributes, including the group avatar and extension information. The createGroup method is deprecated.

chatClient
  .createGroupVNext({
    groupName: "groupname",
    avatar: "group avatar",
    description: "this is my group",
    members: ["user1", "user2"],
    // Whether the group is public. Public groups can be found by group ID; private groups cannot.
    isPublic: true,
    // Whether join requests require approval by the group owner or admins. Only valid for public groups.
    needApprovalToJoin: false,
    // Whether regular members can invite others. Only valid for private groups.
    allowMemberToInvite: true,
    // Whether an invitee must confirm before joining.
    inviteNeedConfirm: false,
    // The maximum number of members. The default is 200; the upper limit depends on your pricing plan.
    maxMemberCount: 200,
    // Group extension information (up to 8 KB).
    extension: JSON.stringify({ info: "group info" }),
  })
  .then((res) => {
    console.log(res);
  });

Join and leave a chat group

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

  1. Call getPublicGroups 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 approval parameter of the group type is set to false, the request from the user is accepted automatically and the chat group members receive the membersPresence callback.
    • If the approval parameter is set to true, the chat group owner and chat group admins receive the requestToJoin callback and determine whether to accept the request from the user.

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

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

// Call getPublicGroups to list public groups by page.
let limit = 20,
  cursor = globalCursor;
let options = {
  limit: limit,
  cursor: cursor,
};
chatClient.getPublicGroups(options).then((res) => console.log(res));

// Call joinGroup to send a join request to a chat group.
const options = {
  groupId: "groupId",
  message: "I am Tom",
};
chatClient.joinGroup(options).then((res) => console.log(res));

// Call leaveGroup to leave a chat group.
const options = {
  groupId: "groupId",
};
chatClient.leaveGroup(options).then((res) => console.log(res));

Retrieve the member list of a chat group

Since SDK v1.4.0, call getGroupMembers to retrieve the chat group member list with pagination. Each entry includes the member's user ID, role, and the time they joined the group. The listGroupMembers method is deprecated.

// cursor: the position to start from. Pass an empty string for the first page; for subsequent pages, pass res.data.cursor from the previous result.
// limit: the number of members to retrieve per page. The default is 50; the upper limit depends on the server.
chatClient
  .getGroupMembers({ cursor: "", limit: 50, groupId: "groupId" })
  .then((res) => {
    console.log(res);
  });

Listen for chat group events

Users can call addEventHandler to listen for chat group events.

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

chatClient.addEventHandler("handlerId", {
  onGroupEvent: function (msg) {
    switch (msg.operation) {
      // Occurs on the other devices of the group owner when a group is created.
      case "create":
        break;
      // Occurs when all chat group members are unmuted.
      case "unmuteAllMembers":
        break;
      // Occurs when all chat group members are muted.
      case "muteAllMembers":
        break;
      // Occurs when a member is removed from the chat group allow list.
      case "removeAllowlistMember":
        break;
      // Occurs when a member is added to the chat group allow list.
      case "addUserToAllowlist":
        break;
      // Occurs when a member deletes a chat group shared file.
      case "deleteFile":
        break;
      // Occurs when a member uploads a chat group shared file.
      case "uploadFile":
        break;
      // Occurs when a member deletes a chat group announcement.
      case "deleteAnnouncement":
        break;
      // Occurs when a member updates a chat group announcement.
      case "updateAnnouncement":
        break;
      // Occurs when a member is removed from the chat group mute list.
      case "unmuteMember":
        break;
      // Occurs when a member is add to the chat group mute list.
      case "muteMember":
        break;
      // Occurs when a chat group admin is removed from the admin list.
      case "removeAdmin":
        break;
      // Occurs when a chat group member is added to the admin list.
      case "setAdmin":
        break;
      // Occurs when the chat group owner is changed.
      case "changeOwner":
        break;
      // Occurs when an invitee accepts the group invitation automatically.
      case "directJoined":
        break;
      // Occurs when a single group member leaves a chat group. Except the member who left, all group members receive this callback.
      case "memberAbsence":
        break;
      // Occurs when one or more group members leave a chat group. Except the members who left, all group members receive this callback. Available since SDK v1.4.0.
      case "membersAbsence":
        break;
      // Occurs when a single user joins a chat group. Except the new member, all group members receive this callback.
      case "memberPresence":
        break;
      // Occurs when one or more users join a chat group. Except the new members, all group members receive this callback. Available since SDK v1.4.0.
      case "membersPresence":
        break;
      // Occurs when a user is removed from a chat group.
      case "removeMember":
        break;
      // Occurs when an invitee declines a group invitation.
      case "rejectInvite":
        break;
      // Occurs when an invitee accepts a group invitation.
      case "acceptInvite":
        break;
      // Occurs when a user receives a group invitation.
      case "inviteToJoin":
        break;
      // Occurs when the chat group owner or admin rejects the join request.
      case "joinPublicGroupDeclined":
        break;
      // Occurs when the chat group owner or admin approves the join request.
      case "acceptRequest":
        break;
      // Occurs when the chat group owner and admins receive a join request.
      case "requestToJoin":
        break;
      // Occurs when the chat group owner disbands the chat group.
      case "destroy":
        break;
      default:
        break;
    }
  },
});

Contact Us

+1 (408) 879-5885

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

AgoraCopyright © 2026 AgoraAll rights reserved