Group Management (iOS)

Last updated: 2020-10-12 14:54:10

    Group Types

    Instant Messaging (IM) supports the following group types:

    • A work group for friends (Work) is like an ordinary WeChat group. After a work group is created, a user can only join the group by being invited by a friend who is a member of the group. The invitation does not need to be accepted by the invitee or approved by the group owner.
    • A public group (Public) is like a QQ group. After a public group is created, the group owner can specify group admins. When a user searches the group ID and initiates a request to join the group, the request must be approved by the group owner or admin before the user can join the group.
    • A temporary meeting group (Meeting) allows users to join and exit freely and supports viewing historical messages from before the user joined the group. Meeting groups can integrate Tencent Real-Time Communication (TRTC), such as in audio and video conference and online education scenarios.
    • A live streaming group (AVChatRoom) allows users to join and exit freely, supports an unlimited number of members, and does not store message history. Live streaming groups can be used with Live Video Broadcasting (LVB) to support the on-screen comments.

    The following table describes the features and limitations of each group type:

    Feature Item Work Public Meeting AVChatRoom
    Available member roles Group owner and ordinary member Group owner, group admin, and ordinary member Group owner, group admin, and ordinary member Group owner and ordinary member
    Requesting to join a group Unsupported Supported with group owner or group admin approval required Supported with no approval required Supported with no approval required
    Joining the group via invitation by a member Supported Unsupported Unsupported Unsupported
    Group owner can quit the group Supported Unsupported Unsupported Unsupported
    Who can modify the group profile Any group member Group owner and group admin Group owner and group admin Group owner
    Who can kick group members out of the group Group owner Group owner and group admin, but group admins can only kick ordinary group members out of the group Group members cannot be removed. The same effect can be achieved by muting members.
    Who can mute members Muting members is not supported Group owner and group admin, but group admin can only mute ordinary group members Group owner
    Unread message count Supported Supported Unsupported Unsupported
    Viewing historical messages from before a user joined Unsupported Unsupported Supported Unsupported
    Storage of historical messages on the cloud Unsupported
    Number of groups
    • Trial Edition: up to 100 existing groups, and disbanded groups do not count against the quota
    • Pro Edition or Flagship Edition: unlimited
    • Trial Edition: up to 10 existing groups, and disbanded groups do not count against the quota
    • Pro Edition: up to 50 existing groups, and disbanded groups do not count against the quota
      You can upgrade to an unlimited number of live streaming groups by purchasing value-added service
    • Flagship Edition: unlimited
    Number of group members
    • Trial Edition: 20 per group
    • Pro Edition: 200 per group by default, which can be increased to 2,000 per group via value-added service
    • Flagship Edition: 2,000 per group by default, which can be increased to 6,000 per group via value-added service
    Unlimited number of group members

    Note:

    In the Pro Edition or Flagship Edition SDKAppID, the maximum net increase in group quantity per day is 10,000 for all group types by default. The maximum number of free groups is 100,000 per month, and you will need to pay for groups exceeding the free quota.

    Group Management

    Creating a group

    Simple API

    You can quickly create a group by calling the createGroup API and specifying groupType, groupID, and groupName.

    Advanced API

    If you want to initialize group information (for example, group introduction, group profile photo, and initial group members) when creating a group, call the createGroup API in the V2TIMManager+Group.h management class.

    // Sample code: create a work group using the advanced createGroup API 
    V2TIMGroupInfo *info = [[V2TIMGroupInfo alloc] init];
    info.groupName = @"testWork";
    info.groupType = @"Work";
    NSMutableArray *memberList = [NSMutableArray array];
    V2TIMCreateGroupMemberInfo *memberInfo = [[V2TIMCreateGroupMemberInfo alloc] init];
    memberInfo.userID = @"vinson";
    [memberList addObject:memberInfo];
    [[V2TIMManager sharedInstance] createGroup:info memberList:memberList succ:^(NSString *groupID) {
        // Group created successfully
    } fail:^(int code, NSString *msg) {
        // Failed to create the group
    }];
    • The value of groupType is a string. Valid values: “Work”, “Public”, “Meeting”, and “AVChatRoom”. For more information on the differences among group types, see Group Types.
    • groupID specifies the group ID, which uniquely identifies a group. Do not create groups with the same groupID in a single SDKAppID. If you set groupID to nil, an ID is assigned for your group by default.
    • groupName specifies the group description, which has a maximum length of 30 bytes.

    Joining a group

    The group joining processes for different group types are described below:

    Type Work Group (Work) Social Networking Group (Public) Temporary Meeting Group (Meeting) Live Streaming Group (AVChatRoom)
    How to join the group Must be invited by a group member User joins the group after request is approved by group owner or admin User can join freely User can join freely

    Scenario 1: users can join and quit the group freely

    Temporary meeting groups (Meeting) and live streaming groups (AVChatRoom) can be used for interactive scenarios where users join and exit the group frequently, such as online conferences and fashion show live streams. These groups have the simplest join procedure.

    After a user successfully joins a group by calling joinGroup, all group members (including the joining user) receive the onMemberEnter callback.

    Scenario 2: users must be invited to the group

    Similar to WeChat and WeChat Work groups, work groups (Work) are suitable for communication in a work environment. The interaction pattern is designed to disable proactive group joining and only allows users to be invited to the group by group members.

    A group member calls inviteUserToGroup to invite a user to the group, and then all group members (including the inviter) receive the onMemberInvited callback.

    Scenario 3: users join the group after their requests are approved

    Social networking groups (Public) are similar to the interest groups and tribes in QQ. Any user can request to join the group, but will not become a member of the group until the request is approved by the group owner or admin. While approval is required by default, the group owner or admin can call the setGroupInfo API to set the group joining option (V2TIMGroupAddOpt) to “forbid anyone to join” or “disable the approval process”.

    • V2TIM_GROUP_ADD_FORBID: forbid anyone to join the group.
    • V2TIM_GROUP_ADD_AUTH: (default) group owner or admin approval is required to join the group.
    • V2TIM_GROUP_ADD_ANY: disable the approval process to allow any user to join the group.

    The following diagram illustrates the process of group joining that requires approval:

    1. The user sends a request to join the group
      The user calls joinGroup to apply to join the group.
    2. The group owner or admin processes the group joining application
      After the onReceiveJoinApplication callback is received, the group owner or admin calls getGroupApplicationList to get the list of group joining applications, and approves or rejects an application with acceptGroupApplication or refuseGroupApplication.
    3. The user receives the result
      The user receives the onApplicationProcessed callback in V2TIMGroupListener. If isAgreeJoin is true, the application is approved. Otherwise, the application is rejected. If the application is approved, all members (including the requestor) receive the onMemberEnter callback.

    Quitting a group

    Call quitGroup to quit a group. The user who quits the group then receives the onQuitFromGroup callback and other group members receive the onMemberLeave callback.

    Note:

    The group owners of social networking groups (Public), temporary meeting groups (Meeting), and live streaming groups (AVChatRoom) are not allowed to quit the group. Instead, the group owner can disband the group.

    Disbanding a group

    Call dismissGroup to disband a group. Then all group members receive the onGroupDismissed callback.

    Note:

    • For social networking groups (Public), temporary meeting groups (Meeting), and live streaming groups (AVChatRoom), the group owner can disband the group at any time.
    • For work groups (Work), the group owner does not have the permission to disband the group. To disband the group, you must have your business server call the RESTful API for disbanding groups.

    Getting the list of joined groups

    Call getJoinedGroupList to get a list of work groups (Work), social networking groups (Public), and temporary meeting groups (Meeting) the current user has joined. Live streaming groups (AVChatRoom) will not be included in this list.

    Group Profiles and Group Settings

    Getting group profiles

    Call getGroupsInfo to get the group profile of one or more groups at a time. To get the group profiles of multiple groups by a single call, pass in multiple groupID at a time.

    Modifying group profiles

    Call setGroupInfo to modify the group profile. When the modification is complete, all group members receive the onGroupInfoChanged callback.

    Note:

    • For work groups (Work), all group members can modify the basic group profile.
    • For social networking groups (Public) and temporary meeting groups (Meeting), only the group owner and admin can modify the basic group profile.
    • For live streaming groups (AVChatRoom), only the group owner can modify the group profile.
    // Sample code: modify the group profile
    V2TIMGroupInfo *info = [[V2TIMGroupInfo alloc] init];
    info.groupID = @"the ID of the group for which you want to modify the group profile";
    info.faceURL = @"http://xxxx";
    [[V2TIMManager sharedInstance] setGroupInfo:info succ:^{
        // Group profile modified successfully
    } fail:^(int code, NSString *msg) {
        // Failed to modify the group profile
    }];

    Setting the group message receiving option

    Any group member can call the setReceiveMessageOpt API to modify the group message receiving option. Available values are as follows:

    • V2TIM_GROUP_RECEIVE_MESSAGE: messages will be received when the user is online and APNs push notifications will be received when the user is offline.
    • V2TIM_GROUP_NOT_RECEIVE_MESSAGE: no group messages will be received.
    • V2TIM_GROUP_RECEIVE_NOT_NOTIFY_MESSAGE: messages will be received when the user is online and no push notification will be received when the user is offline.

    The group message receiving option allows you to mute group messages:

    • No group message will be received
      With the group message receiving option set to V2TIM_GROUP_NOT_RECEIVE_MESSAGE, no group message will be received, and the conversation list will not be updated.
    • Group messages will be received but the user will not be notified. A badge without the unread count will be displayed on the conversation list interface

      Note:

      The unread count feature needs to be enabled for this to work. Therefore it only applies to work groups (Work) and social networking groups (Public).

      With the group message receiving option set to V2TIM_GROUP_RECEIVE_NOT_NOTIFY_MESSAGE, when new group messages are received and the conversation list needs to update, get the unread count through unreadCount. Use recvOpt to verify that the group message receiving option is V2TIM_GROUP_RECEIVE_NOT_NOTIFY_MESSAGE and then display a badge without the unread count.

    Group Attributes (Custom Group Fields)

    Based on API 2.0, we designed new custom group fields called "group attributes". Their features are as follows:

    1. Clients can directly add, delete, modify, and query group attributes without the need for console configuration.
    2. A maximum of 16 group attributes is supported. The maximum size supported for each group attribute is 4 KB, and the maximum size supported for all group attributes is 16 KB.
    3. Currently, only AVChatRooms are supported.
    4. The SDK can call initGroupAttributes, setGroupAttributes, and deleteGroupAttributes simultaneously up to 10 times every 5 seconds. If this limit is exceeded, the 8511 error code is returned via callback. The backend can call these APIs simultaneously up to 5 times per second. If this limit is exceeded, the 10049 error code is returned.
    5. The SDK can call getGroupAttributes up to 20 times every 5 seconds.

    Based on group attributes, we can manage the mic for voice chat rooms. When a member turns the mic on, you can set a group attribute to manage the information of the mic-on member. When the member turns the mic off, you can delete the corresponding group attribute. Other members can obtain the group attribute list to show the mic position list.

    Initializing group attributes

    Call initGroupAttributes to initialize group attributes. If the group originally has group attributes, the original group attributes will be cleared.

    Setting group attributes

    Call setGroupAttributes to set group attributes. If a set group attribute does not exist, it will be automatically added.

    Deleting group attributes

    Call deleteGroupAttributes to delete the specified group attribute. If the keys field is set to nil, all group attributes will be cleared.

    Obtaining group attributes

    Call getGroupAttributes to obtain the specified group attribute. If the keys field is set to nil, all group attributes will be obtained.

    Updating group attributes

    If any group attribute is updated, all group attributes will be updated via the onGroupAttributeChanged callback.

    Managing group members

    Getting group member list

    Call getGroupMemberList to get the list of group members of a given group. The list contains profile information about individual members, such as user ID (userID), group name card (nameCard), profile photo (faceUrl), nickname (nickName), and time of joining the group (joinTime).
    As a group may have a large number of members (even over 5,000), so this API supports two advanced properties: filter and nextSeq.

    Filters (filter)

    When calling getGroupMemberList, you can specify filter to pull the information list of certain group roles.

    Filter Description
    V2TIM_GROUP_MEMBER_FILTER_ALL Pull the information list of all group members
    V2TIM_GROUP_MEMBER_FILTER_OWNER Pull the information list of the group owner
    V2TIM_GROUP_MEMBER_FILTER_ADMIN Pull the information list of the group admin
    V2TIM_GROUP_MEMBER_FILTER_COMMON Pull the information list of ordinary group members
    // Sample code: pull the profile of the group owner using the filter parameter
    [[V2TIMManager sharedInstance] getGroupMemberList:@"testGroup" filter:V2TIM_GROUP_MEMBER_FILTER_OWNER 
    nextSeq:0 succ:^(uint64_t nextSeq, NSArray<V2TIMGroupMemberInfo *> *memberList) {
        // Pulled successfully
    } fail:^(int code, NSString *msg) {
        // Failed to pull
    }];

    Pulling paginated results with nextSeq

    In many cases, it makes more sense for the user interface to display the first page of the group member list instead of the complete list. More group members can be pulled when the user clicks "Next Page" or pull the list to refresh. For this scenario, you can apply the method of pulling paginated results.

    The getGroupMemberList API returns a maximum of 50 members at a time. You can use the pagination flag nextSeq to pull a paginated group member list. In the first attempt to pull the group member list, enter 0 for nextSeq. When the first pull succeeds, getGroupMemberList’s callback result V2TIMGroupMemberInfoResult contains the nextSeq field.

    • If nextSeq is 0, the complete group member list has been pulled.
    • If nextSeq is greater than 0, there remains group member information to be pulled. You can then decide whether to make another call to pull group member information based on the user’s action on the UI. In the second pull, you need to pass the nextSeq in the V2TIMGroupMemberInfoResult returned from the previous pull as a parameter to the getGroupMemberList API.
    // Sample code: pull paginated group member list using nextSeq
    [[V2TIMManager sharedInstance] getGroupMemberList:@"testGroup" filter:V2TIM_GROUP_MEMBER_FILTER_ALL nextSeq:0 
    succ:^(uint64_t nextSeq, NSArray<V2TIMGroupMemberInfo *> *memberList) {
        // If nextSeq is greater than 0, make another pull
        if (nextSeq > 0) {
            [[V2TIMManager sharedInstance] getGroupMemberList:@"testGroup" filter:V2TIM_GROUP_MEMBER_FILTER_ALL 
                    nextSeq:nextSeq succ:^(uint64_t nextSeq, NSArray<V2TIMGroupMemberInfo *> *memberList) {
                // The second pull succeeded
            } fail:^(int code, NSString *msg) {
                // The second pull failed
            }];
        }
        // The first pull succeeded
    } fail:^(int code, NSString *msg) {
        // The first pull failed
    }];

    Getting the profiles of group members

    Call getGroupMembersInfo to get the profiles of group members in batches. You can pass in multiple userID at a time to improve network transmission efficiency.

    Modifying group member profiles

    The group owner or admin can call the setGroupMemberInfo API to modify group-related information of members, including group name card (nameCard), group member role (role), and muting duration (muteUntil).

    Muting

    The group owner or admin can mute a group member and set the muting duration (in seconds) via muteGroupMember. Muting information is stored in the muteUntil field of the group member. After the group member is muted, all group members (including the muted member) receive the onGroupMemberInfoChanged callback.
    The group owner or admin can mute the entire group via the setGroupInfo API by setting allMuted to true. There is no time limit for muting the group. The group can be unmuted by setting allMuted to NO.

    Removing group members

    The group owner or admin can call the kickGroupMember API to remove a group member. As a live streaming group (AVChatRoom) can have unlimited members, it does not support the API. You can use muteGroupMember to achieve the same effect instead.
    After the member is removed, all group members (including the removed member) receive the onMemberKicked callback.

    Changing group member roles

    The group owner can call setGroupMemberRole to change the role of a member of a social networking group (Public) or temporary meeting group (Meeting). Roles available for changing are ordinary member and group admin.

    • After a member is set as group admin, all group members (including the new admin) receive the onGrantAdministrator callback.
    • After the admin role is removed for a member,all group members (including the member with admin role removed) receive the onRevokeAdministrator callback.

    Transferring a group

    The group owner can call transferGroupOwner to transfer the ownership of the group to another group member.
    After the group ownership is transferred, all group members receive the onGroupInfoChanged callback, where the type of V2TIMGroupChangeInfo is V2TIM_GROUP_INFO_CHANGE_TYPE_OWNER and the value is the UserID of the new group owner.

    FAQs

    1. Can a live streaming group (AVChatRoom) continue to receive messages after it is disconnected and then reconnected?

    Yes, but since live streaming groups (AVChatRoom) do not support storing message history in the cloud, it cannot pull the messages that were sent when it was disconnected.

    2. Why doesn’t the group receive notifications when a user joins or quits the group?

    Verify the group type:

    • Temporary meeting groups (Meeting) do not support member change notifications.
    • Live streaming groups (AVChatRoom) can receive up to 40 messages per second, and it prioritizes the receiving and sending of high-priority messages and discards messages with the lowest priority first once the frequency limit is exceeded.

    3. Why does the unread count of temporary meeting groups (Meeting) remain at 0?

    Temporary meeting groups (Meeting) and live streaming groups (AVChatRoom) are designed for conference and live streaming scenarios respectively, and they do not support the unread count feature.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help