Group Overview

Instant Messaging (IM) supports multiple group types. For more information on their characteristics and limits, see Group System. A group is identified by a unique ID that enables different operations.

Group Management

Obtaining your group list

This API is used to obtain your group list when you need to render or refresh My Groups. For more information, see Group.

Note：

The list of groups returned by this API does not include TIM.TYPES.GRP_AVCHATROOM (live streaming groups).

API

tim.getGroupList();

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback parameter of then is IMResponse. IMResponse.data.groupList contains the list of groups.
• The callback parameter of catch is IMError.

Example

• Group profile information that is retrieved by default:

  // This API retrieves the following information by default: group type, group name, group profile photo, and the time of the last message.
  let promise = tim.getGroupList();
  promise.then(function(imResponse) {
  console.log(imResponse.data.groupList); // Group list.
  }).catch(function(imError) {
  console.warn('getGroupList error:', imError); // Information on the failure in obtaining the group list.
  });
  

• Other group profile information to retrieve:

  // If the profile fields that are retrieved by default fail to meet your requirements, you can retrieve additional profile fields by referring to the following code.
  let promise = tim.getGroupList({
   groupProfileFilter: [TIM.TYPES.GRP_PROFILE_OWNER_ID],
  });
  promise.then(function(imResponse) {
  console.log(imResponse.data.groupList); // Group list.
  }).catch(function(imError) {
  console.warn('getGroupList error:', imError); // Information on the failure in obtaining the group list.
  });
  

Obtaining the detailed group profile

For more information, see Group.

API

tim.getGroupProfile(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. You can obtain group profiles from IMResponse.data.group.
• The callback parameter of catch is IMError.

Example

let promise = tim.getGroupProfile({
  groupID: 'group1',
  groupCustomFieldFilter: ['key1','key2']
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group);
}).catch(function(imError) {
  console.warn('getGroupProfile error:', imError); // Information on the failure in obtaining the detailed group profile.
});

Creating a group

For more information, see Group.

Note：

After this API is used to create TIM.TYPES.GRP_AVCHATROOM (live streaming group), you must call joinGroup to join the group and enable the messaging process.

API

tim.createGroup(options);

Request Parameters

options is of the Object type. Its values are as follows:

memberList parameter description

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. You can obtain group profiles from IMResponse.data.group.
• The callback parameter of catch is IMError.

Example

// Create a work group.
let promise = tim.createGroup({
  type: TIM.TYPES.GRP_WORK,
  name: 'WebSDK',
  memberList: [{userID: 'user1'}, {userID: 'user2'}] // If memberList is specified, userID must also be specified.
});
promise.then(function(imResponse) { // Created successfully.
  console.log(imResponse.data.group); // The profile of the created group.
}).catch(function(imError) {
  console.warn('createGroup error:', imError); // Information on the failure in creating the group.
});

Disbanding a group

This API is used by a group owner to disband a group.

Note：

The group owner cannot disband work groups.

API

tim.dismissGroup(groupID);

Request Parameters

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. You can obtain the ID of the disbanded group from IMResponse.data.groupID.
• The callback parameter of catch is IMError.

Example

let promise = tim.dismissGroup('group1');
promise.then(function(imResponse) { // Disbanded successfully.
  console.log(imResponse.data.groupID); // The ID of the disbanded group.
}).catch(function(imError) {
  console.warn('dismissGroup error:', imError); // Information on the failure in disbanding the group.
});

Updating a group profile

API

tim.updateGroupProfile(options);

Request Parameters

options is of the Object type. Its values are as follows:

groupCustomField parameter description

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. You can obtain the modified group profile from IMResponse.data.group.
• The callback parameter of catch is IMError.

Example

let promise = tim.updateGroupProfile({
  groupID: 'group1',
  name: 'new name', // Modify the group name.
  introduction: 'this is introduction.', // Modify the group notice.
  // Starting from v2.6.0, group members can receive group prompts about custom group field modifications and obtain related content. For more information, see Message.payload.newGroupProfile.groupCustomField.
  groupCustomField: [{ key: 'group_level', value: 'high'}] // Modify the group-level custom field.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group) // The detailed group profile after modification.
}).catch(function(imError) {
  console.warn('updateGroupProfile error:', imError); // Information on the failure in modifying the group profile.
});

Applying to join a group

This API is called when a user applies to join a group.

Note：

• Users cannot apply to join a work group and can only be added to the group through the addGroupMember method.
• TIM.TYPES.GRP_AVCHATROOM (livestreaming groups) support two ways to join a group:
• Users join the group in the normal manner after login. All APIs in the SDK can be called normally.
• Users join the group anonymously without login. Messages will be received, but any APIs that require authentication cannot be called.
• Only TIM.TYPES.GRP_AVCHATROOM (livestreaming groups) support anonymous group joining.
• Users can join only one livestreaming group at a time. For example, when a user joins live streaming group B when already in live streaming group A, the SDK quits group A first and then joins group B.

API

tim.joinGroup(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data contains the following property values:

  Name	Description
  status	The status of the group joining process. Valid values: TIM.TYPES.JOIN_STATUS_WAIT_APPROVAL: waiting for the admin’s approval TIM.TYPES.JOIN_STATUS_SUCCESS: joined successfully TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: already in the group
  group	The group profile displayed when the user joins the group.

• The callback parameter of catch is IMError.

Example

let promise = tim.joinGroup({ groupID: 'group1', type: TIM.TYPES.GRP_AVCHATROOM });
promise.then(function(imResponse) {
  switch (imResponse.data.status) {
    case TIM.TYPES.JOIN_STATUS_WAIT_APPROVAL: break; // Waiting for the admin’s approval.
    case TIM.TYPES.JOIN_STATUS_SUCCESS: // Joined the group successfully.
      console.log(imResponse.data.group); // The profile of the group.
      break;
    case TIM.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: //Already in the group
      break;
    default: break;
  }
}).catch(function(imError){
  console.warn('joinGroup error:', imError); // Information on the failure in joining the group.
});

Quitting a group

A group owner can only quit work groups. After the group owner quits, the work group has no group owner.

API

tim.quitGroup(groupID);

Request Parameters

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.groupID is the ID of the group that the user quits.
• The callback parameter of catch is IMError.

Example

let promise = tim.quitGroup('group1');
promise.then(function(imResponse) {
  console.log(imResponse.data.groupID); // The ID of the group that the user quits.
}).catch(function(imError){
  console.warn('quitGroup error:', imError); // Information on the failure in quitting the group.
});

Searching for a group by group ID

This API is used to search for a group by group ID.

Note: work groups (TIM.TYPES.GRP_WORK) can not be searched for.

API

tim.searchGroupByID(groupID);

Request Parameters

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile.
• The callback parameter of catch is IMError.

Example

let promise = tim.searchGroupByID('group1');
promise.then(function(imResponse) {
  const group = imResponse.data.group; // Group profile.
}).catch(function(imError) {
  console.warn('searchGroupByID error:', imError); // Information on the failure in searching for the group.
});

Transferring a group

This API is used to transfer a group. Only the group owner has the permission to perform this operation.

Note: only the group owner can transfer the ownership of a group. Livestreaming groups (TIM.TYPES.GRP_AVCHATROOM) cannot be transferred.

API

tim.changeGroupOwner(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile.
• The callback parameter of catch is IMError.

Example

let promise = tim.changeGroupOwner({
  groupID: 'group1',
  newOwnerID: 'user2'
});
promise.then(function(imResponse) { // Transferred successfully.
  console.log(imResponse.data.group); // Group profile.
}).catch(function(imError) { // Failed to transfer the group.
  console.warn('changeGroupOwner error:', imError); // Information on the failure in transferring the group.
});

Processing an application to join a group

This API is used to approve or reject an application to join a group.

Note：

If a group has multiple administrators, all online administrators receive a group system notification when someone applies to join the group. If one of the administrators has approved or rejected the application, other administrators cannot change the result.

API

tim.handleGroupApplication(options);

Request Parameters

The options parameter is of the Object type. It contains the following property values:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile.
• The callback parameter of catch is IMError.

Example

let promise = tim.handleGroupApplication({
  handleAction: 'Agree',
  handleMessage: 'Welcome',
  message: message // The message instance of the group system notification for an application to join a group.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile.
}).catch(function(imError){
  console.warn('handleGroupApplication error:', imError); // Error information.
});

Setting the notification type for group messages

API

tim.setMessageRemindType(options);

Request Parameters

The options parameter is of the Object type. It contains the following property values:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile.
• The callback parameter of catch is IMError.

Example

let promise = tim.setMessageRemindType({ groupID: 'group1', messageRemindType: TIM.TYPES.MSG_REMIND_DISCARD }); // Reject the message.
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // The group profile that is displayed after modification.
}).catch(function(imError) {
  console.warn('setMessageRemindType error:', imError);
});

Group Member Management

Getting group member list

Note：

• Starting from v2.6.2, this API can be used to pull the muting stop timestamps of group members (muteUntil). Based on its value, the access side can find out whether the member is muted and the remaining muting time.
• In versions earlier than v2.6.2, this API can be used to get profile information including profile photo and nickname, which is sufficient to meet the rendering requirements of the group member list. To get detailed information such as member muting stop timestamp (muteUntil), use getGroupMemberProfile.
• This API is used to pull a paginated list of group members and not the complete list. To get the complete list of group members (memberNum), use getGroupProfile.

For more information, see GroupMember.

API

tim.getGroupMemberList(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.memberList is the list of group members. For more information, see GroupMember.
• The callback parameter of catch is IMError.

Example

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.
}).catch(function(imError) {
  console.warn('getGroupMemberList error:', imError);
});
// Starting from v2.6.2, this API can be used to pull the muting stop timestamps 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);
});

Getting the profiles of group members

Note：

• This API requires SDK v2.2.0 or later.
• The maximum number of users in each query is 50. If the length of the array passed in is greater than 50, only the first 50 users will be queried and the rest will be discarded.

For more information, see GroupMember.

API

tim.getGroupMemberProfile(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.memberList is the list of group members whose profiles are queried successfully. For more information, see GroupMember.
• The callback parameter of catch is IMError.

Adding group members

The rules for adding group members are as follows:

• TIM.TYPES.GRP_PRIVATE (work group): any group member can invite users to the group and acceptance by the invitee is not required.
• TIM.TYPES.GRP_PUBLIC (social networking group)/TIM.TYPES.GRP_CHATROOM (temporary meeting group): only the app admin can invite users to the group and acceptance by the invitee is not required.
• TIM.TYPES.GRP_AVCHATROOM (livestreaming group): no member (including the app admin) is allowed to invite any user to the group.

For more information, see GroupGroupMember and Differences in joining a group.

API

tim.addGroupMember(options);

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data contains the following property values:

  Name	Type	Description
  successUserIDList	Array<String>	List of userIDs that were added successfully
  failureUserIDList	Array<String>	List of userIDs that failed to be added
  existedUserIDList	Array<String>	List of userIDs that were already in the group
  group	Group	Group profile that is displayed after the API is called

• The callback parameter of catch is IMError.

Example

let promise = tim.addGroupMember({
  groupID: 'group1',
  userIDList: ['user1','user2','user3']
});
promise.then(function(imResponse) {
  console.log(imResponse.data.successUserIDList); // The userIDList of group members that were added successfully.
  console.log(imResponse.data.failureUserIDList); // The userIDList of group members that failed to be added.
  console.log(imResponse.data.existedUserIDList); // The userIDList of group members that were already in the group.
  console.log(imResponse.data.group); // The group profile that is displayed after the group members are added.
}).catch(function(imError) {
  console.warn('addGroupMember error:', imError); // Error information.
});

Deleting group members

This API is used to delete group members. Only the group owner can delete group members.

API

tim.deleteGroupMember(options)

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the updated group profile.
• The callback parameter of catch is IMError.

Example

let promise = tim.deleteGroupMember({groupID: 'group1', userIDList:['user1'], reason: 'You are deleted from the group because you have violated the group rules.'});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // Group profile that is displayed after one or more group members are deleted.
  console.log(imResponse.data.userIDList); // List of userIDs of the deleted group members.
}).catch(function(imError) {
  console.warn('deleteGroupMember error:', imError); // Error information.
});

Muting or unmuting a group member

This API is used to set the muting duration for a group member. You can mute or unmute a group member. The muting and unmuting features are unavailable in work groups (TIM.TYPES.GRP_WORK).

Note：

Only the group owner and the group admin have the permissions for this operation.

• The group owner can mute and unmute the admin and ordinary group members.
• The admin can mute and unmute ordinary group members.

API

tim.setGroupMemberMuteTime(options)

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile displayed after modification.
• The callback parameter of catch is IMError.

Example

let promise = tim.setGroupMemberMuteTime({
  groupID: 'group1',
  userID: 'user1',
  muteTime: 600 // The user is muted for 10 minutes. If the value is set to 0, the user is unmuted.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // The group profile that is displayed after modification.
  console.log(imResponse.data.member); // The group member’s profile that is displayed after modification.
}).catch(function(imError) {
  console.warn('setGroupMemberMuteTime error:', imError); // Information on the failure in muting the group member.
});

Setting or canceling the admin

This API is used to change the role of a group member. Only the group owner has the permission to perform this operation.

API

tim.setGroupMemberRole(options)

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile displayed after modification.
• The callback parameter of catch is IMError.

Example

let promise = tim.setGroupMemberRole({
  groupID: 'group1',
  userID: 'user1',
  role: TIM.TYPES.GRP_MBR_ROLE_ADMIN // Set user1 as the admin of group1.
});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // The group profile that is displayed after modification.
  console.log(imResponse.data.member); // The group member’s profile that is displayed after modification.
}).catch(function(imError) {
  console.warn('setGroupMemberRole error:', imError); // Error information.
});

Modifying a group member’s name card

This API is used to modify a group member’s name card.

• The group owner can set the name cards of all members.
• The group admin can set its own name card and the name cards of ordinary group members.
• Ordinary group members can only set their own name cards.

API

tim.setGroupMemberNameCard(options)

Request Parameters

options is of the Object type. Its values are as follows:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile displayed after modification.
• The callback parameter of catch is IMError.

Example

let promise = tim.setGroupMemberNameCard({ groupID: 'group1', userID: 'user1', nameCard: 'Name card' });
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // The group profile that is displayed after modification.
  console.log(imResponse.data.member); // The group member’s profile that is displayed after modification.
}).catch(function(imError) {
  console.warn('setGroupMemberNameCard error:', imError); // Information on the failure in setting a group member’s name card.
});

Modifying a group member custom field

This API is used to modify a group member custom field.

Ordinary group members can only modify their own custom fields.

API

tim.setGroupMemberCustomField(options)

Request Parameters

options is of the Object type. Its values are as follows:

The memberCustomField parameter contains the following property values:

Response

This API returns a Promise object.

• The callback function parameter for then is IMResponse. IMResponse.data.group is the group profile displayed after modification.
• The callback parameter of catch is IMError.

Example

let promise = tim.setGroupMemberCustomField({ groupID: 'group1', memberCustomField: [{key: 'group_member_test', value: 'test'}]});
promise.then(function(imResponse) {
  console.log(imResponse.data.group); // The group profile that is displayed after modification.
  console.log(imResponse.data.member); // The group member’s profile that is displayed after modification.
}).catch(function(imError) {
  console.warn('setGroupMemberCustomField error:', imError); // Information on the failure in modifying the group member custom field.
});

Group Notification

This API is used to send a group notification in a group when a user is invited to the group or deleted from the group. The access side can determine whether to display the message to group members as needed or ignore all the messages.
IM provides multiple types of group notifications. For more information, see Message.GroupTipPayload.

The parameters of a group notification are described above. The system sends a group notification to all group members at the appropriate time. For example, when a user quits or joins a group, the system sends the corresponding group notification to all group members.

Group System Notification

When a user applies to join a group, the group admin receives a system message about the application. The admin can accept or reject the application, and the IM SDK sends the result to the access side via a corresponding group system notification, which is then displayed to the user by the access side.
IM provides multiple types of system notifications. For more information, see Types, Constants, and Meanings of Group System Notifications.

let onGroupSystemNoticeReceived = function(event) {
  const type = event.data.type; // The type of the group system notification. For more information, see Message.GroupSystemNoticePayload. 
  const message = event.data.message; // The message instance of the group system notification. For more information, see Message.
  console.log(message.payload); // The content of the message. This describes the payload of the group system notification.
};
tim.on(TIM.EVENT.GROUP_SYSTEM_NOTICE_RECEIVED, onGroupSystemNoticeReceived);

operationType description

The parameters of a group system notification are described above. The system sends a group system notification to all group members at the appropriate time. For example, when user1 is deleted from a group, the system sends the corresponding group system notification to user1.