please select
Docs Overview/
Chat/
SDK/
Web/
Group/
Group Member Management/

Group Member Management

Description

Group member management includes pulling the member list, muting group members, removing group members, granting permissions, and transferring the group ownership.

Getting the Group Member List

Caution
1. This API supports pulling the muting stop timestamp (muteUntil) of group members. Based on this value, you can determine if a member is muted and the remaining muting time.
2. This API retrieves group members in pages and cannot be used directly to get the total number of group members. To get the total number of group members (memberCount), please use getGroupProfile.
3. When the API returns an offset of 0, it means all group members have been retrieved.
4. The following special restrictions are added for audio-video groups (AVChatRoom):
The Enterprise Edition supports pulling up to 1,000 recently joined group members, with new members ranked first. To use this feature, you need to purchase the Enterprise Edition package and enable the feature in the Chat Console.
When the Enterprise Edition uses this API, the SDK will ignore the count parameter, and a single query will return up to 500 group members by default.
On the Ultimate edition, this API can be called up to one time per three seconds. To query the group member list periodically, you are advised to call the API once every ten seconds.
The group member profile information only supports the fields userID, nick, avatar, and joinTime. To set nick and avatar information, please call: updateMyProfile.
5. The Enterprise Edition supports fetching the list of designated tagged group members in live groups (AVChatRoom) based on the filter parameter. Please refer to: markGroupMemberList to tag group members.
To enable the feature of online group member lists in live groups for the Advanced Edition, please log in to the Chat Console and modify the relevant configuration. The configuration page is shown below:



API
chat.getGroupMemberList(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
count
Number
The number of entries to be fetched. Default value: 15, Maximum value: 100, to avoid response failure due to large packages. If more than 100 is passed in, only the first 100 will be fetched (the Enterprise Edition for live groups ignores the count parameter when using this API).
offset
Number
Offset, default is to start pulling from 0.
Return values
Promise
Example
let promise = chat.getGroupMemberList({
   groupID: 'group1',
   count: 30,
   offset:0,
 }); // Pull 30 group members starting from 0
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
}).catch(function(imError) {
  console.warn('getGroupMemberList error:', imError);
});
// This API supports pulling the muting end timestamp of group members.
let promise = tim.getGroupMemberList({
   groupID: 'group1',
   count: 30,
   offset:0,
 }); // Pull 30 group members starting from 0
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
  for (let groupMember of imResponse.data.memberList) {
    if (groupMember.muteUntil * 1000  > Date.now()) {
      console.log(`${groupMember.userID} muted`);
    } else {
      console.log(`${groupMember.userID} not muted`);
    }
  }
}).catch(function(imError) {
    console.warn('getGroupMemberProfile error:', imError);
});
// The Enterprise Edition Package supports retrieving the list of online members in the live group
let promise = chat.getGroupMemberList({
   groupID: 'group1',
   offset:0, // Default is to start pulling from 0
 });
promise.then(function(imResponse) {
  console.log(imResponse.data.memberList); // Group member list
}).catch(function(imError) {
  console.warn('getGroupMemberList error:', imError);
});

Mute

Mute specific group members

Caution
1. TencentCloudChat.TYPES.GRP_WORK type groups (i.e., friend work groups) do not support this operation.
2. TencentCloudChat.TYPES.GRP_AVCHATROOM type groups (i.e., live chat groups) do not support this operation.
3. To ban or kick out group members in live chat groups, you need to purchase the Enterprise Edition Package and use the deleteGroupMember interface.
4. If you need to mute all members, please refer to updateGroupProfile.
5. It supports setting a mute duration for community members within topics by passing topicID as groupID.
6. Only the group owner and administrators have this permission:
The group owner can mute/unmute administrators and ordinary group members.
Administrators can mute/unmute ordinary group members.
API
chat.setGroupMemberMuteTime(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID or topic ID
userID
String
User ID
muteTime
Number
Mute duration, in seconds. For example, setting it to 1000 means muting the user for 1000 seconds from now; setting it to 0 means unmuting.
Return values
Promise
Example
let promise = chat.setGroupMemberMuteTime({
  groupID: 'group1',
  userID: 'user1',
  muteTime: 600 // Mute for 10 minutes; set to 0 to unmute
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.group); // New group profile
}).catch(function(imError) {
  console.warn('setGroupMemberMuteTime error:', imError); // Error information
});
// Set the period for muting a group member in the topic
let promise = chat.setGroupMemberMuteTime({
  groupID: 'topicID',
  userID: 'user1',
  muteTime: 600 // Mute for 10 minutes; set to 0 to unmute
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.group); // New group profile
}).catch(function(imError) {
  console.warn('setGroupMemberMuteTime error:', imError); // Error information
});

Mute the entire group

// Global Mute
let promise = chat.updateGroupProfile({
  groupID: 'group1',
  muteAllMembers: true, // `true`: mute all; `false`: unmute all
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group) // Detailed group profile after modification
}).catch(function(imError) {
  console.warn('updateGroupProfile error:', imError); // Error information
});

Kick out

Caution
1. The flagship package supports removing live group members. You can achieve the effect of [Ban Group Members] in live chat groups by calling this interface.
2. The kick out duration field is supported only by live chat groups (AVChatRoom).
3. After a group member is removed from a live chat group, within the kick out duration, if the user wants to rejoin the group, the app admin needs to call the REST API to unban them. After the kick out duration, the user can proactively join the live chat group again.
API
chat.deleteGroupMember(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID or topic ID
userIDList
Array
List of IDs of the group members to be removed
reason
String | undefined
Reason for kicking out
duration
Number
Kick-out duration must be greater than 0 (supported only by live broadcast groups)
Return values
Promise
Example
// Removing group members from non-live broadcast groups
let promise = chat.deleteGroupMember({
   groupID: 'group1',
   userIDList:['user1'],
   reason: 'You violated the rules, I'm kicking you out!',
 });
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile after group member removal
  console.log(imResponse.data.userIDList); // List of userID of the removed group member
}).catch(function(imError) {
  console.warn('deleteGroupMember error:', imError); // Error information
});
// Removing group members from live broadcast groups
let promise = chat.deleteGroupMember({
   groupID: 'group1',
   userIDList:['user1'],
   reason: 'You violated the rules, I'm kicking you out!',
   duration: 60,
 });
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile after group member removal
  console.log(imResponse.data.userIDList); // List of userID of the removed group member
}).catch(function(imError) {
  console.warn('deleteGroupMember error:', imError); // Error information
});

Changing the Role of a Group Member

Caution
1. TencentCloudChat.TYPES.GRP_WORK type groups (i.e., friend work groups) do not support this operation.
2. TencentCloudChat.TYPES.GRP_AVCHATROOM type groups (i.e., live chat groups) do not support this operation.
API
chat.setGroupMemberRole(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID or topic ID
userID
String
User ID
role
String
Valid values:
TencentCloudChat.TYPES.GRP_MBR_ROLE_ADMIN (Group Administrator),
TencentCloudChat.TYPES.GRP_MBR_ROLE_MEMBER (Group Regular Member),
TencentCloudChat.TYPES.GRP_MBR_ROLE_CUSTOM (Custom Group Member Roles, supported only by the Community)
Return values
Promise
Example
let promise = chat.setGroupMemberRole({
  groupID: 'group1',
  userID: 'user1',
  role: TencentCloudChat.TYPES.GRP_MBR_ROLE_ADMIN // Set user: user1 as an admin in group ID: group1
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // New group profile
  console.log(imResponse.data.group); // New group profile
}).catch(function(imError) {
  console.warn('setGroupMemberRole error:', imError); // Error information
});

Getting Group Online Users

Caution
1. Currently, this API is supported only by audio-video groups (AVChatRoom).
2. When you are not in an audio-video group or use this API to query the number of users in a non-audio-video group, the SDK returns memberCount as 0. It is recommended to control the frequency of calling this interface to query the number of users in an audio-video group to once every 5-10 seconds.
API
chat.getGroupOnlineMemberCount(groupID);
Parameters
Name
Type
Description
groupID
String
Group ID
Return values
Promise
Example
// Querying the Number of Online Users in an Audio-Video Group
let promise = chat.getGroupOnlineMemberCount('group1');
promise.then(function(imResponse) {
  console.log(imResponse.data.memberCount);
}).catch(function(imError) {
  console.warn('getGroupOnlineMemberCount error:', imError); // Error information
});