ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of group management, allowing you to create a group, ungroup, join and leave a group, and maintain the group relation chain.
With the group management feature, you can create different types of group chats as needed, such as colleague groups, social groups, fan groups, and more.
After user A logs in to the ZIM SDK on a client, the user can call the createGroup
method to create a group with advanced settings. In this case, user A logged on this client is the group owner, and users on other clients can join this group using the groupID
.
You can check whether the group is created through the ZIMGroupCreatedCallback
callback. For more information about error codes, see Error codes.
groupID
generation. A group ID can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~', and cannot start with a pound sign (#). If this parameter is empty, the ZIM server automatically generates a value. We recommend that you set a meaningful group ID generation rule. You can associate the group ID with your business account system.createGroup
method to create a group, the user automatically joins the group without calling the joinGroup
method.// The groupID parameter can contain up to 32 bytes in length, including digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'. It cannot start with a pound sign (#).
// The groupName parameter can contain up to 50 bytes in length, with no limit on characters.
var groupInfo = { groupID: '', groupName: '', groupAvatarUrl: '' };
var userIDs = [];
// Set the group joining mode and the upper limit of the group number
var config1 = {
/**
* Group joining verification mode, only supports ZIM SDK version 2.15.0 and above
* 0: (Default) Anyone can join the group directly.
* 1: Group owner or administrator approval is required to join the group.
* 2: Other users are prohibited from joining the group.
*/
joinMode: 1,
/**
* Invite mode, only supports ZIM SDK version 2.15.0 and above
* 0: (Default) Any group member can invite external members to join the group.
* 1: Only group owners or administrators can invite external members to join the group.
*/
inviteMode: 1,
/**
* Invite target user verification mode, only supports ZIM SDK version 2.15.0 and above
* 0: (Default) The user automatically becomes a group member without the consent of the invitee.
* 1: The invitee becomes a group member after consent.
*/
beInviteMode: 1,
/**
* Group member limit, only supports ZIM SDK version 2.15.0 and above
* Value range: [0, the default maximum number of group members for the package].
*/
maxMemberCount: 100 // Limit the total number of group members to 100
};
zim.createGroup(groupInfo, userIDs, config1)
.then(function ({ groupInfo, userList, errorUserList }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
If you want users to automatically obtain group history messages after joining a group, please contact the ZEGOCLOUD technical support team for configuration.
After logging in to the ZIM SDK, users can apply to join or be invited to join a group created by user A.
If a user successfully joins the group, all group members (including the user) receive the groupMemberStateChanged
and groupStateChanged
callbacks.
// Callback notification of group member status change.
zim.on('groupMemberStateChanged', function (zim, { groupID, state, event, userList, operatedInfo }) {
console.log('groupMemberStateChanged', groupID, state, event, userList, operatedInfo);
});
// Callback notification of group status change.
zim.on('groupStateChanged', function (zim, { state, event, groupInfo, operatedInfo }) {
console.log('groupStateChanged', state, event, groupInfo, operatedInfo);
});
The user calls the corresponding method to apply to join a group based on the joinMode
of the group.
If the joinMode
is set to 0
, the user calls the joinGroup
method and passes in the groupID
to join the group without approval. If the groupID
does not exist, the operation fails.
var groupID = '';
// Join the group on another client.
zim.joinGroup(groupID)
.then(function ({ groupInfo }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
If the joinMode
is set to 1
:
The user calls the sendGroupJoinApplication
method to send an application.
// Apply to join the group
var groupID = '';
var config = {
wording: 'XXXX applies to join the group' // Application message
};
zim.sendGroupJoinApplication(groupID, config)
.then(function ({ groupID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
The group owner or administrator receives the application notification by listening for the groupApplicationListChanged
event.
// Listen for groupApplicationListChanged event.
zim.on('groupApplicationListChanged', (zim, { action, applicationList }) => {
// Added group application, you can now update the group application list UI.
console.log(action, applicationList);
});
The group owner or administrator handles the application.
The group owner or administrator calls the acceptGroupJoinApplication
method to approve the application.
var userID = '';
var groupID = '';
var config = {};
zim.acceptGroupJoinApplication(userID, groupID, config)
.then(function ({ groupID, userID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
- The group owner or administrator calls the [`rejectGroupJoinApplication`\|_blank](/article/api?doc=zim_API~javascript_web~class~ZIM#reject-group-join-application) method to reject the application.
```js
var userID = '';
var groupID = '';
var config = {};
zim.rejectGroupJoinApplication(userID, groupID, config)
.then(function ({ groupID, userID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
```
The user applying to join the group, the group owner or administrator, and the method caller receive the groupApplicationUpdated
callback.
```js
// Listen for groupApplicationUpdated event.
zim.on('groupApplicationUpdated', (zim, { applicationList }) => {
// The group application has changed. You can update the group application list UI at this time
console.log(applicationList);
});
```
A group member can invite a user to the group by calling one of the following methods.
Make sure that the invitee has been registered by calling the login
method; otherwise, the operation fails.
inviteUsersIntoGroup
: Invite a user to a group.
var groupID = '';
// Added to the group by group members.
var userIDs = [];
zim.inviteUsersIntoGroup(userIDs, groupID)
.then(function ({ groupID, userList, errorUserList }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
sendGroupInviteApplications:Send a group invitation application to the user.
```js
// Send an invitation application.
var userIDs = [];
var groupID = '';
var config = {
wording: 'Invite to join the group' // Application message.
};
zim.sendGroupInviteApplications(userIDs, groupID, config)
.then(function ({ groupID, errorUserList }) {
// The operation is successful, and the users who failed to invite are obtained through errorUserList.
})
.catch(function (err) {
// Operation failed.
});
```
The following table describes the operation results of different methods called by different roles in a group in inviteMode
and beInviteMode
mode.
beInviteMode | inviteMode | Method | Caller | Result |
---|---|---|---|---|
0: None |
0: Any |
inviteUsersIntoGroup |
All group members |
The invitee joins the group without approval. |
sendGroupInviteApplicationsToUserIDs |
The invitee joins the group without approval, with no application generated. |
|||
1: Admin |
inviteUsersIntoGroup |
Ordinary members |
Failed. |
|
Group owner or administrator |
The invitee joins the group without approval. |
|||
sendGroupInviteApplicationsToUserIDs |
Ordinary members |
Failed. |
||
Group owner or administrator |
The invitee joins the group without approval, with no application generated. |
|||
1: Auth |
0: Any |
inviteUsersIntoGroup |
All group members |
An application is generated and sent to the invitee for approval. |
sendGroupInviteApplicationsToUserIDs |
An application is generated and sent to the invitee for approval. If the caller is the group owner or administrator, the groupApplicationListChanged callback is generated. |
|||
1: Admin |
inviteUsersIntoGroup |
Ordinary members |
Failed. |
|
Group owner or administrator |
An application is generated and sent to the invitee for approval. |
|||
sendGrsendGroupInviteApplicationsToUserIDsoupInviteApplications |
Ordinary members |
Failed. |
||
Group owner or administrator |
An application is generated and sent to the invitee for approval. If the caller is the group owner or administrator, the groupApplicationListChanged callback is generated. |
If the beInviteMode
is set to 1
, the invitee and inviter (the group owner or administrator) receive the notification in the groupApplicationListChanged
callback. The invitee can perform the following operations on the application:
Calls the acceptGroupInviteApplication
method to approve the application and join the group.
var inviterUserID = '';
var groupID = '';
// Agree to join the group invitation.
var config = {};
zim.acceptGroupInviteApplication(inviterUserID, groupID, config)
.then(function ({ groupInfo, inviterUserID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
Call the rejectGroupInviteApplication
method to reject the application.
var inviterUserID = '';
var groupID = '';
// Refuse to join the group invitation.
var config = {};
zim.rejectGroupInviteApplication(inviterUserID, groupID, config)
.then(function ({ groupID, inviterUserID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
If the beInviteMode
is set to 1
, the invitee and inviter (the group owner or administrator) receive the approval notification in the groupApplicationUpdated
callback.
// Listen for groupApplicationUpdated event.
zim.on('groupApplicationUpdated', (zim, { applicationList }) => {
// If there is a change in the group application, you can update the group application list UI at this time.
console.log(applicationList);
});
A group member can leave a group or be removed from a group.
After a group member leaves a group, the local list of conversations is retained, and historical group messages can be viewed.
After logging in to the ZIM SDK, the group member calls the leaveGroup
method and passes in the groupID
. If the groupID
does not exist, the operation fails. After the group member leaves the group, all group members receive the groupMemberStateChanged
callback.
If the group owner leaves the group, the group ownership is automatically transferred to the first group member. If all group members leave the group, the group is automatically disbanded.
var groupID = '';
// Leave a group.
zim.leaveGroup(groupID)
.then(function ({ groupID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
The group owner calls the kickGroupMembers
method and passes in the groupID
and userIDList
(list of users to be removed). If the groupID
does not exist, the operation fails. After one or more group members are removed, all group members (including the group owner and the removed group members) receive the groupMemberStateChanged
callback.
kickGroupMembers
method to remove a group member, who does not need to be logged in or approve the removal.userID
of the user to be removed must be in the list of group members; otherwise, the operation fails.var groupID = '';
// The group owner removes one or more group members from the group.
var userIDs = [];
zim.kickGroupMembers(userIDs, groupID)
.then(function ({ groupID, kickedUserIDs, errorUserList }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK, the group owner calls the dismissGroup
method to disband a group. After the group is disbanded, all group members receive the groupStateChanged
callback.
dismissGroup
method to disband a group.var groupID = '';
zim.dismissGroup(groupID)
.then(function ({ groupID }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
// Register a callback to monitor "group status change".
zim.on('groupStateChanged', function (zim, { state, event, groupInfo, operatedInfo }) {
console.log('groupStateChanged', state, event, groupInfo, operatedInfo);
});
After logging in to the ZIM SDK, a user calls the queryGroupList
method to query the list of joined groups.
zim.queryGroupList()
.then(function ({ groupList }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK, a user calls the searchLocalGroups
method and passes in the config
and callback
parameters to search for joined groups by condition.
The search result is returned in the ZIMGroupsSearchedResult
callback.
The ZIM applet SDK does not support this API.
// Search for joined groups with names containing "zego".
var config = {
count: 10, // Number of search results.
nextFlag: 0,
keywords: ['zego'], // et the keyword to "zego", up to 5 keywords are supported. When multiple keywords are set, the search results will only display local messages that contain all keywords at the same time.
isAlsoMatchGroupMemberUserName: true, // // Search for joined groups with names containing "zego".
var config = {
count: 10, // Number of search results
nextFlag: 0,
keywords: ['zego'], // Set the keyword to "zego", up to 5 keywords are supported. When multiple keywords are set, the search results will only display local messages that contain all keywords at the same time
isAlsoMatchGroupMemberUserName: true, // If the group member user name contains "zego", the search results will include the group member
isAlsoMatchGroupMemberNickname: false,
};
zim.searchLocalGroups(config)
.then(function ({ groupSearchInfoList, nextFlag }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
If a group is muted, group members cannot send messages to the group.
After logging in to the ZIM SDK, a user can mute or unmute a group on which the user has management permission by calling the muteGroup
method and passing in parameters to specify the group ID, mute mode, duration, and role.
The ZIM SDK supports three mute modes:
role
value is 3
) are muted.The result is returned in the ZIMGroupMutedResult
callback.
If you want to block specific group members from posting, please refer to Set mute status for group members - Manage group members.
// Configure group muting.
const config = {
mode: 3, //Group members of specified roles are muted.
duration: 30, //hese members are muted for 30 seconds.
roles:[3,5],//Group members whose `role` value is `3` or `5` are muted.
};
// Enable mutingvar isMute = true;
var groupID = 'group';
zim.muteGroup(isMute, groupID, config)
.then(function ({ groupID, isMute, mutedInfo }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After a group is muted or unmuted, all group members receive the groupMutedInfoUpdated
callback and know which roles are muted or unmuted.
zim.on('groupMutedInfoUpdated', function (zim, { groupID, mutedInfo, operatedInfo}) {
console.log('groupMutedInfoUpdated', groupID, mutedInfo, event, userList, operatedInfo);
});
If you want to block specific group members from posting, please refer to Set mute status for group members - Manage group members.
To check whether a user is in a group, call any of the following methods:
For group chats, the result is indicated by the isDisabled
property of ZIMGroupConversation
.
Valid values of isDisabled
:
true
: The user is not in the group. If the user leaves the group or is removed from the group, or the group is disbanded, the value of isDisabled
is false
.false
: The user is in the group.After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupJoinMode
method to update the group joining mode.
After the mode is updated, all group members receive the groupVerifyInfoUpdated
callback.
// Listen for groupVerifyInfoUpdated event.
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
console.log(groupID, verifyInfo.joinMode);
});
var groupID = '';
// Update the verification mode for others to join the group
var joinMode = 1;
zim.updateGroupJoinMode(joinMode, groupID)
.then(function ({ groupID, mode }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupInviteMode
method to update inviteMode of the group.
After the mode is updated, all group members receive the groupVerifyInfoUpdated
callback.
// Listen for groupVerifyInfoUpdated event.
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
console.log(groupID, verifyInfo.inviteMode);
});
var groupID = '';
// Updated verification mode for inviting others to join the group.
var inviteMode = 1;
zim.updateGroupInviteMode(inviteMode, groupID)
.then(function ({ groupID, mode }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK, the group owner or administrator calls the updateGroupBeInviteMode
method to update beInviteMode.
After the mode is updated, all group members receive the groupVerifyInfoUpdated
callback.
// Listen for groupVerifyInfoUpdated event.
zim.on('groupVerifyInfoUpdated', (zim, { groupID, verifyInfo, operatedInfo }) => {
console.log(groupID, verifyInfo.beInviteMode);
});
var groupID = '';
// Update beInviteMode.
var beInviteMode = 1;
zim.updateGroupBeInviteMode(beInviteMode, groupID)
.then(function ({ groupID, mode }) {
// Operation successful.
})
.catch(function (err) {
// Operation failed.
});
After logging in to the ZIM SDK, a user calls the queryGroupApplicationList
method to query the list of applications. The query result contains applications sent from and to the user.
// Query the group application list.
var config = {
count: 30, // Single query number.
nextFlag: 0 // Anchor point, fill in 0 for the first query, and use the nextFlag returned by the current query as the anchor point for the next query.
};
zim.queryGroupApplicationList(config)
.then(function ({ nextFlag, applicationList }) {
// Operation successful, use nextFlag as the anchor point for the next query.
})
.catch(function (err) {
// Operation failed.
});