ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of group member management, allowing you to query the group member list and group member info, change the group owner, and more.
After you log in to the ZIM SDK and join a group, if you want to know the members of his group, query the group's member list in pages by calling the queryGroupMemberListByGroupID interface. A single call to the interface can obtain up to 100 members. If the passed count
exceeds 100, it will be processed as 100.
You will receive a notification through the callback ZIMGroupMemberListQueriedResult
after the query succeeds.
As of the current version, when this interface is called for the first time to pull the list of group members, the avatars of group members can be retrieved. If you call this interface again, you can get the avatar information of new users, but the avatar information of existing users will not be updated.
To get the latest avatars of group members, please call the interface queryGroupMemberInfo to query group member info.
queryGroupMemberList(groupID: string, config: ZIMGroupMemberQueryConfig): Promise<ZIMGroupMemberListQueriedResult>
Parameter | Type | Required | Description |
---|---|---|---|
groupID | string | Yes | The ID of the group that you want to query the group member list. |
config | ZIMGroupMemberQueryConfig |
Yes | Advanced configurations of query the group member list. |
Promise | ZIMGroupMemberListQueriedResult |
Yes | Callback for the results of query the group member list. |
// Get group member list.
var groupID = '';
// If count exceeds 100, it will be treated as 100.
var config = { count: 10, nextFlag: 0 };
zim.queryGroupMemberList(groupID, config)
.then(function ({ groupID, userList, nextFlag }) {
// Query successful.
})
.catch(function (err) {
// Query failed.
});
After you log in to the ZIM SDK and join a group, if you want to know the information of a member of the group, query the member's personal information by calling the queryGroupMemberInfo
interface.
You will receive the specific info through the callback ZIMGroupMemberInfoQueriedResult
after the query succeeds.
queryGroupMemberInfo(userID: string, groupID: string): Promise<ZIMGroupMemberInfoQueriedResult>
Parameter | Type | Required | Description |
---|---|---|---|
userID | string | Yes | The ID of the member you want to query. |
groupID | string | Yes | The ID of the group that the member you want to query is in. |
Promise | ZIMGroupMemberInfoQueriedResult |
Yes | Callback for the results of query the group member info. |
// Get the info of a specified group member.
var groupID = '';
var userID = '';
zim.queryGroupMemberInfo(userID, groupID)
.then(function ({ groupID, userInfo }) {
// Query successful.
})
.catch(function (err) {
// Query failed.
});
To set an alias after joining a group, call the setGroupMemberNickname
method.
The group owner can set the alias of all group members. But the group members can only set their own aliases.
You will receive a notification through the callback ZIMGroupMemberNicknameUpdatedResult
after the alias is set successfully.
setGroupMemberNickname(
nickname: string,
forUserID: string,
groupID: string,
): Promise<ZIMGroupMemberNicknameUpdatedResult>
Parameter | Type | Required | Description |
---|---|---|---|
nickname | string | Yes | The alias you want to set. |
forUserID | string | Yes | The ID of the member you want to set an alias. |
groupID | string | Yes | The ID of the group that the member is in. |
Promise | ZIMGroupMemberNicknameUpdatedResult |
Yes | Callback for the results of set an alias for a group member. |
// Set an alias. Note: The group owner can set the alias of all group members. But the group members can only set their own aliases.
var groupID = '';
var forUserID = '';
var nickname = '';
zim.setGroupMemberNickname(nickname, forUserID, groupID)
.then(function ({ groupID, forUserID, nickname }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
// Set up and listen for the callback groupMemberInfoUpdated.
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});
For a group owner to set a role for a group member, call the setGroupMemberRole
method. You can set the group member to a regular member or admin.
After the setting is successful, the group owner can receive the setting result through ZIMGroupMemberRoleUpdatedResult .
Group members can receive notifications of user role changes throughonGroupMemberInfoUpdated.
The ZIM SDK supports setting users as group owners, administrators, and regular members by default. In a group, the group owner has all client permissions and can perform all group functions. Administrators have most client permissions, while regular members have the fewest client permissions. The specific client permissions for each role are shown in the table below:
Client Permissions | Group Owner (corresponding enum value: 1) |
Administrator (corresponding enum value: 2) |
Regular Member (corresponding enum value: 3) |
---|---|---|---|
Modify group avatar, group name, group notice | Supported |
Supported |
Supported |
Modify group attributes | |||
Modify group member nickname | Supported, can be used for all group role users |
Supported, can be used for all regular members |
Supported, can only be used for oneself |
Recall group member messages | |||
Kick out members | Not supported |
||
Mute individual group members | |||
Mute specific group roles | |||
Set group member roles | Not supported |
||
Transfer group ownership | |||
Dismiss the group | |||
Mute all members |
setGroupMemberRole(role: number, forUserID: string, groupID: string): Promise<ZIMGroupMemberRoleUpdatedResult>
Parameter | Type | Required | Description |
---|---|---|---|
role | number | Yes | The role you want to set to.
|
forUserID | string | Yes | The ID of the member you want to set a role for. |
groupID | string | Yes | The ID of the group that the member is in. |
Promise | ZIMGroupMemberRoleUpdatedResult |
Yes | Callback for the results of set a role. |
// The group owner sets ordinary member users as administrators.
var groupID = '';
var forUserID = '';
var role = 2;
zim.setGroupMemberRole(role, forUserID, groupID)
.then(function ({ groupID, forUserID, role }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
// Set up and listen for the callback groupMemberInfoUpdated.
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});
For a group owner to transfer the group ownership, call the transferGroupOwner
method with the toUserID
(the ID of the member you want to transfer the ownership to).
All group members will receive a notification through the callback groupMemberInfoUpdated after the group owner is changed.
transferGroupOwner(toUserID: string, groupID: string): Promise<ZIMGroupOwnerTransferredResult>
Parameter | Type | Required | Description |
---|---|---|---|
toUserID | string | Yes | The ID of the group member you want to transfer the ownership to. |
groupID | string | Yes | The ID of the group where the group owner is in. |
Promise | ZIMGroupOwnerTransferredResult |
Yes | Callback for the results of transfer the group ownership. |
// Change the group owner.
var groupID = '';
var toUserID = '';
zim.transferGroupOwner(toUserID, groupID)
.then(function ({ groupID, toUserID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
// Set up and listen for the callback groupMemberStateChanged.
zim.on('groupMemberStateChanged', function (zim, { groupID, state, event, userList, operatedInfo }) {
console.log('groupMemberStateChanged', groupID, state, event, userList, operatedInfo);
});
// Set up and listen for the callback groupMemberInfoUpdated.
zim.on('groupMemberInfoUpdated', function (zim, { groupID, userList, operatedInfo }) {
console.log('groupMemberInfoUpdated', groupID, userList, operatedInfo);
});
To query the number of group members after logging in and joining a group, call the queryGroupMemberCount
method.
You will receive the query results through the callback ZIMGroupMemberCountQueriedResult
.
queryGroupMemberCount(groupID: string): Promise<ZIMGroupMemberCountQueriedResult>
Parameter | Type | Required | Description |
---|---|---|---|
groupID | string | Yes | ID of the group you want to query. |
Promise | ZIMGroupMemberCountQueriedResult | Yes | Callback for querying the number of group members. |
// Query the number of group members.
var groupID = '';
zim.queryGroupMemberCount(groupID)
.then(function ({ groupID, count }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK and joining a group, if you want to search for users within the group based on certain criteria, use the searchLocalGroupMembers interface. By providing the groupID、config、callback, you can search for group members that meet the specified conditions.
The search results will be returned through the ZIMGroupMembersSearchedCallback interface.
ZIM applet SDK does not support this API.
searchLocalGroupMembers(
groupID: string,
config: ZIMGroupMemberSearchConfig,
): Promise<ZIMGroupMembersSearchedResult>
| Parameter | Type | Required | Description |
| ---- | ----| -------| -----|
| groupID | string | Yes| The group ID to be searched (must be a joined group).|
| config | [ZIMGroupMemberSearchConfig\|_blank](/article/api?doc=zim_API~javascript_web~interface~ZIMGroupMemberSearchConfig)| Yes | Group member search configuration.|
| Promise | [ZIMGroupMembersSearchedResult\|_blank](/article/api?doc=zim_API~javascript_web~interface~ZIMGroupMembersSearchedResult) | Yes | The searched group member information can be obtained through this callback.|
#### Description of [ZIMGroupMemberSearchConfig\|_blank](/article/api?doc=zim_API~javascript_web~interface~ZIMGroupMemberSearchConfig)
| Parameter | Type | Required | Description |
| ---- | ----| -------| -----|
| nextFlag | number | No |Query flag, fill in 0 when calling the interface for the first time. When calling the interface again later, fill in the nextFlag returned from the callback in order to obtain the remaining data. |
| count | numberstring | Yes | The upper limit of group member information that can be obtained by searching once is 30. It is recommended to be less than 20 to reduce performance overhead.|
| keywords | string[] | Yes | Search keywords, up to 5 are supported, otherwise an error will be reported. For example: if you pass in "1" and "2", the search results will only display group members whose names contain both the keywords "1" and "2".|
| isAlsoMatchGroupMemberNickname | boolean | No |Whether the search scope includes group member nicknames, whether the search scope includes group member nicknames, the default is false. |
#### Sample code
```javascript
// Search a group for members with "zego" in their name
var config = {
count: 10, // number of search results
nextFlag: 0,
keywords: ['zego'], // Set the keywords to "zego", supports up to 5. When multiple keywords are set, the search results will only show local messages that contain all the keywords at the same time.
isAlsoMatchGroupMemberNickname: true, // If a group member has a nickname that includes zego, the search results will include that group member.
};
zim.searchLocalGroupMembers('groupID', config)
.then(function ({ groupID, userList, nextFlag }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging into the ZIM SDK, you can mute or unmute specific members within the groups they manage. By calling the muteGroupMembers|_blank interface, you can modify the mute status of up to 100 group members in bulk. The mute duration can be permanent or up to a maximum of 604,800 seconds (7 days).
After the settings are successfully applied, the operating user will receive notifications through muteGroupMembers.
Once a mute or unmute operation is successful, all group members will receive groupMemberInfoUpdated, which informs them about the members who are unable to speak in the group or have had their mute status lifted.
If you want to mute certain group members , please refer Manage groups - Mute group.
var isMute = true;
var userIDs = ["user_1", "user_2", "user_3"];
var groupID = "group_id";
var config = {
duration: 30, // Set the mute time to 30 seconds.
};
zim.muteGroupMembers(isMute, userIDs, groupID, config)
.then(function ({ groupID, isMute, duration, mutedUserIDs, errorUserList }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging into the ZIM SDK, if you want to know the list of muted members in their group, you can use queryGroupMemberMutedListByGroupID for querying.
Upon a successful query, the operating user can obtain specific information through ZIMGroupMemberMutedListQueriedCallback.
// Query the member list of muted members in the group
var groupID = "group_id";
var config = {
count: 100,
nextFlag: 0,
}
zim.queryGroupMemberMutedList(groupID, config)
.then(function ({ groupID, userList, nextFlag }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
To actively retrieve the mute status of the current user in a group, please use any of the following methods:
Retrieve the mutedExpiredTime
from the ZIMConversation
object in the returned result, which indicates the mute duration in seconds.
The explanation of the mutedExpiredTime
value is as follows:
If the current user is both muted due to group role restrictions (refer to Manage groups - Mute or unmute group, and individually muted(refer to the section Set mute status for group members in this article), the value of mutedExpiredTime
will be determined by taking the maximum value between the "group mute time" and the "individual mute time".