グループ管理
Feature Description
The group management feature allows creating a group, joining a group, getting the joined groups, leaving a group, or disbanding a group.
Group Event Listener
Sample
let onGroupListUpdated = function(event) {console.log(event.data);// Array that stores Group instances};chat.on(TencentCloudChat.EVENT.GROUP_LIST_UPDATED, onGroupListUpdated);
Searching a Group
Note:
Groups of type
TencentCloudChat.TYPES.GRP_WORK
cannot be searched.API
chat.searchGroupByID(groupID);
Parameter
Name | Type | Description |
groupID | String | group ID. |
Returned value
Promise
Sample
let promise = chat.searchGroupByID('group1');promise.then(function(imResponse) {const group = imResponse.data.group;}).catch(function(imError) {console.warn('searchGroupByID error:', imError);});
Creating a Group
Note:
1. After this API is used to create
TencentCloudChat.TYPES.GRP_AVCHATROOM
, the joinGroup
API needs to be called to join the group to enable the messaging process.2. This API can create a topic-enabled community.
API
chat.createGroup(options);
Parameter
The
options
parameter is of the Object
type. It contains the following attribute values:Name | Type | Description |
name | String | Group name, which can contain up to 30 bytes. |
type | String | Group type. Valid values: TencentCloudChat.TYPES.GRP_WORK (work group, which is the default value)TencentCloudChat.TYPES.GRP_PUBLIC (public group)TencentCloudChat.TYPES.GRP_MEETING (meeting group)TencentCloudChat.TYPES.GRP_AVCHATROOM (audio-video group)TencentCloudChat.TYPES.GRP_COMMUNITY (community) |
groupID | String | undefined | Group ID. If it is not specified, a unique ID will be automatically created for the group. |
introduction | String | undefined | Group introduction, which can contain up to 240 bytes. |
notification | String | undefined | Group notice, which can contain up to 300 bytes. |
avatar | String | undefined | Group profile photo URL, which can contain up to 100 bytes. |
maxMemberNum | Number | undefined | Maximum number of group members. Default value: 200 for a work group 2,000 for a public group 10,000 for a meeting group unlimited for an audio-video group |
joinOption | String | Method to join a group. Valid values: TencentCloudChat.TYPES.JOIN_OPTIONS_FREE_ACCESS TencentCloudChat.TYPES.JOIN_OPTIONS_NEED_PERMISSION (approval required)TencentCloudChat.TYPES.JOIN_OPTIONS_DISABLE_APPLY (no group join allowed)Note: It cannot be modified for TencentCloudChat.TYPES.GRP_WORK , TencentCloudChat.TYPES.GRP_MEETING , and TencentCloudChat.TYPES.GRP_AVCHATROOM groups. Work groups cannot be joined on request, and meeting groups and audio-video groups can be joined freely. |
inviteOption | String | undefined | Group inviting option: TencentCloudChat.TYPES.INVITE_OPTIONS_FREE_ACCESS : allow free group invitingTencentCloudChat.TYPES.INVITE_OPTIONS_NEED_PERMISSION : require approval for group invitingTencentCloudChat.TYPES.INVITE_OPTIONS_DISABLE_INVITE : forbid group invitingNote: The property is not supported for groups of type TencentCloudChat.TYPES.GRP_AVCHATROOM , but it is supported for other types of groups. |
memberList | Array | undefined | List of up to 500 existing group members. No group members can be added when an audio-video group is created. The array elements are as structured below: userID --- String --- userID of the group member, which is requiredrole --- String --- member role, which can only be Admin , indicating to add and set the group member as the adminmemberCustomField --- Array |
groupCustomField | Array | undefined | Custom group field, which is unavailable by default. For more information on how to enable a custom group field, see Custom Group Field. |
isSupportTopic | Boolean | It is required for creating a topic-enabled community. Valid values: true : create a topic-enabled community; false : create an ordinary community. |
Returned value
Promise
Sample
// Create a work grouplet promise = chat.createGroup({type: TencentCloudChat.TYPES.GRP_WORK,name: 'WebSDK',memberList: [{userID: 'user1',// Group member custom field.// By default, this parameter is not available and needs to be enabled.// For details, see Custom Fields.memberCustomField: [{key: 'group_member_test', value: 'test'}]}, {userID: 'user2'}] // If `memberList` is specified, `userID` must also be specified.});promise.then(function(imResponse) { // Created successfullyconsole.log(imResponse.data.group); // Profile of the created group// A member list is specified during group creation// but a certain user has exceeded the limit on the number of groups a single user can join.// If you specify userX, who has joined N groups (maximum number of groups userX can join)// as a member of the group during group creation, userX cannot join the group properly.// The SDK places the information of userX in overLimitUserIDList for the access side to process.// List of users who have exceeded the limit on the number of groups a single user can join.console.log(imResponse.data.overLimitUserIDList);}).catch(function(imError){console.warn('createGroup error:', imError); // Failed to create the group});
// Create a topic-enabled communitylet promise = chat.createGroup({type: TencentCloudChat.TYPES.GRP_COMMUNITY,name: 'WebSDK',isSupportTopic: true,});promise.then(function(imResponse) { // Created successfullyconsole.log(imResponse.data.group); // Profile of the created group}).catch(function(imError){console.warn('createGroup error:', imError); // Failed to create the group});
// Create a group with inviteOptionlet promise = chat.createGroup({type: TencentCloudChat.TYPES.GRP_PUBLIC,name: 'WebSDK',inviteOption: TencentCloudChat.TYPES.INVITE_OPTIONS_NEED_PERMISSION,});promise.then(function(imResponse) {console.log(imResponse.data.group);}).catch(function(imError) {console.warn('createGroup error:', imError);});
Joining a Group
The method for joining a group may vary by group type as follows:
Type | Method for Joining a Group |
Work group (Work) | By invitation |
Public group (Public) | On request from the user and on approval from the group owner or admin Inviting to join the group, this feature is not supported by default. You can modify the inviteOption through the updateGroupProfile interface to implement it. |
Meeting group (Meeting) | Free to join Inviting to join the group, this feature is not supported by default. You can modify the inviteOption through the updateGroupProfile interface to implement it. |
Community (Community) | Free to join Inviting to join the group, this feature is not supported by default. You can modify the inviteOption through the updateGroupProfile interface to implement it. |
Audio-video group (AVChatRoom) | Free to join |
Note:
1. Work groups cannot be joined on request, but only through
addGroupMember
.2. A user can join one audio-video group at a time. For example, if a user is already in audio-video group A and attempts to join audio-video group B, the SDK will remove the user from audio-video group A first and then add the user to audio-video group B.
3. To obtain the live group's online member list, you need to purchase the Premium edition. Please refer to
getGroupMemberList.
API
chat.joinGroup(options);
Parameter
The
options
parameter is of the Object
type. It contains the following attribute values:Name | Type | Description |
groupID | String | Group ID |
applyMessage | String | undefined | Remarks |
Returned value
Promise
Sample
let promise = chat.joinGroup({ groupID: 'group1' });promise.then(function(imResponse) {switch (imResponse.data.status) {case TencentCloudChat.TYPES.JOIN_STATUS_WAIT_APPROVAL: // Waiting to be approved by the adminbreak;case TencentCloudChat.TYPES.JOIN_STATUS_SUCCESS: // Joined the group successfullyconsole.log(imResponse.data.group); // Profile of the groupbreak;case TencentCloudChat.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: // The user is already in the group.break;default:break;}}).catch(function(imError){console.warn('joinGroup error:', imError); // Failed to join the group});
Getting the Joined Groups
Note:
1. This interface returns the group list that the SDK has synchronized from the cloud, excluding groups of type
TencentCloudChat.TYPES.GRP_AVCHATROOM
and community groups that support topics.2. The group list returned by the interface only includes the basic information of the group (group type, group name, group avatar, @ information list).
3. If you want to obtain detailed information about a group, please use
getGroupProfile
.API
chat.getGroupList();
Returned value
Promise
Sample
let promise = chat.getGroupList();promise.then(function(imResponse) {console.log(imResponse.data.groupList); // Group list}).catch(function(imError){console.warn('getGroupList error:', imError); // Failed to obtain the group list});
Leaving a Group
Note:
1. A group owner can only leave a work group, after which the work group will have no group owner.
2. After leaving the group, if the login state has not expired, the SDK will still retain the corresponding group conversation. If you want to delete the conversation, please use
deleteConversation
.API
chat.quitGroup(groupID);
Parameter
Name | Type | Description |
groupID | String | Group ID |
Returned value
Promise
Sample
let promise = chat.quitGroup('group1');promise.then(function(imResponse) {console.log(imResponse.data.groupID); // ID of the group that the user leaves}).catch(function(imError){console.warn('quitGroup error:', imError); // Failed to leave the group});
Disbanding a Group
Note:
1. A work group cannot be disbanded.
2. After the group is dissolved, if the login state has not expired, the SDK will still retain the corresponding group conversation. If you want to delete the conversation, please use
deleteConversation
.API
chat.dismissGroup(groupID);
Parameter
Name | Type | Description |
groupID | String | Group ID |
Returned value
Promise
Sample
let promise = chat.dismissGroup('group1');promise.then(function(imResponse) { // Disbanded successfullyconsole.log(imResponse.data.groupID); // ID of the disbanded group}).catch(function(imError){console.warn('dismissGroup error:', imError); // Failed to disband the group});
Transferring a Group
Note:
1. Only group owners have the permission to transfer groups.
2. AVChatRoom (
TencentCloudChat.TYPES.GRP_AVCHATROOM
) cannot be transferred.API
chat.changeGroupOwner(options);
Parameter
The
options
parameter is of the Object
type. It contains the following attribute values:Name | Type | Description |
groupID | String | ID of the group to be transferred |
newOwnerID | String | ID of the new group owner |
Returned value
Promise
Sample
let promise = chat.changeGroupOwner({groupID: 'group1',newOwnerID: 'user2'});promise.then(function(imResponse) { // Transferred successfullyconsole.log(imResponse.data.group); // Group profile}).catch(function(imError) { // Failed to transfer the groupconsole.warn('changeGroupOwner error:', imError); // Failed to transfer the group});
Geting the List of Group Join Requests and Invitations to Join the Group
API
chat.getGroupApplicationList();
Parameter
None
Returned value
Promise
Sample
let promise = chat.getGroupApplicationList();promise.then(function(imResponse) {const { applicationList } = imResponse.data;applicationList.forEach((item) => {// item.applicant - Applicant userID// item.applicantNick - Applicant nickname// item.groupID - group ID// item.groupName - group Name// item.applicationType - Application type: 0 for group join application, 2 for invitation to join the group// item.userID - When applicationType = 2, it is the userID of the invited user.// item.note - reamakechat.handleGroupApplication({handleAction: 'Agree',application: {...item},});});}).catch(function(imError) {console.warn('getGroupApplicationList error:', imError);});
Processing (Approving or Rejecting) a Group Join Request
Note:
1. If there are multiple admins in a group, when a user requests to join the group, all the online admins will receive the system notification of the group join request. If one of the admins processes (approves or rejects) the request, other admins cannot process it again, that is, they cannot modify the processing result.
2. If here are multiple admins in a group, when someone invites a user to join the group, all the online group admins will receive a group system notification for the invitation to join the group. If one of the group admins processes this application through the pending list (agree or reject), other admins cannot process it again, that is, they cannot modify the processing result.
API
chat.handleGroupApplication(options);
Parameter
The
options
parameter is of the Object
type. It contains the following attribute values:Name | Type | Description |
handleAction | String | Processing result. Valid values: Agree , Reject . |
handleMessage | String | undefined | Remarks |
message | Message | Message instance of the group system notification |
application | Object | undefined | group application |
Returned value
Promise
Sample
let promise = chat.handleGroupApplication({handleAction: 'Agree',handleMessage: 'Welcome',// The message instance of the group system notification for an application to join a group.message: message});promise.then(function(imResponse) {console.log(imResponse.data.group); // Group profile}).catch(function(imError){console.warn('handleGroupApplication error:', imError); // Error message});
let promise = chat.getGroupApplicationList();promise.then(function(imResponse) {const { applicationList } = imResponse.data;applicationList.forEach((item) => {if (item.applicationType === 0) {chat.handleGroupApplication({handleAction: 'Agree',application: {...item},});}});}).catch(function(imError) {console.warn('getGroupApplicationList error:', imError);});
let promise = chat.getGroupApplicationList();promise.then(function(imResponse) {const { applicationList } = imResponse.data;applicationList.forEach((item) => {if (item.applicationType === 2) {chat.handleGroupApplication({handleAction: 'Agree',application: {...item},});}});}).catch(function(imError) {console.warn('getGroupApplicationList error:', imError);});