Create and use message groups

Prerequisites

• You have activated the Interactive Messages service.

• After a client logs on, it can send one-to-one messages. Before a client can join a group, the group must exist. You can create a group in one of the following two ways:

  • Create a group using a server-side OpenAPI operation

    API operation: Create a live interactive group

    Note

    • For more information about how to integrate the server-side SDK with your business service, see Server-side SDK integration for Interactive Messages.

    • To call related features using the server-side SDK, you must provide the AccessKey of a Resource Access Management (RAM) user. For more information about how to create a RAM user, grant the required ApsaraVideo Live permissions, and generate an AccessKey, see Create and authorize a RAM user. Ensure that you keep your AccessKey information secure.

  • Create a group by calling the client SDK after logon

    Android SDK operation: Administrator operation: Create a group. For other client SDKs, see Client integration.

    Note

    The role used to generate the logon token must be admin.

Best practices

1. Plan the GroupID.

   • Ensure that each GroupID is unique within your AppID.

   • Associate the GroupID with the ID of the business live channel based on a specific rule. If the ID contains unsupported characters, use Base64 encoding.

   • If you know the live channel ID, you can calculate the corresponding Interactive Messages GroupID without having to record or query it separately.

2. In some business scenarios, using GroupInfo or GroupMeta is crucial for efficiently managing group announcements and status information. The client and the server-side use different names for this feature in the related API operations:

   • On the server-side, it is named groupInfo in OpenAPI operations.

   • In the client API, it is named groupMeta.

   1. When a client calls the joingroup method to join a group, the system returns the ImJoinGroupRsp response, which contains the group metadata (groupMeta).

      After you successfully join the group, you can obtain the related information.

      ImJoinGroupReq req = new ImJoinGroupReq();
      req.groupId = groupId;
      groupInterface.joinGroup(req, new ImSdkValueCallback<ImJoinGroupRsp>() {
          @Override
          public void onSuccess(ImJoinGroupRsp data) {
              
          }
      
          @Override
          public void onFailure(Error error) {
      	}
      });

   2. You can use the following API operations to modify a group.

      • Server-side SDK: Modify live interactive group information.

      • Client SDK: Modify a group.

        Important

        Only the group administrator or group creator can perform this operation.

   3. When group information changes, the system pushes these changes in real time to all clients in the group using the listen for group change messages API operation. This ensures that all users who subscribe to group status updates receive immediate notifications and stay synchronized with the group's latest status.

      // Listen for group changes
      groupManager.addGroupListener(new ImGroupListener() {
          @Override
          public void onMemberChange(String groupId, int memberCount, ArrayList<ImUser> joinUsers, ArrayList<ImUser> leaveUsers) {
              
          }
          @Override
          public void onExit(String groupId, int reason) {
          }
          @Override
          public void onMuteChange(String groupId, ImGroupMuteStatus status) {
          }
          @Override
          public void onInfoChange(String groupId, ImGroupInfoStatus info) {
          }
      });

   4. This information is an open-ended string. You can customize the string format to implement your business protocol.

3. Group creators and administrators.

   • Group creator:

     • When you create a group using a client API operation, the current user becomes the group creator.

     • When you create a group using a server-side API operation, you must specify the creator in the API call.

   • Group administrator:

     Group creators and administrators have specific group permissions that allow them to perform the following operations:

     • Modify group information

     • Mute members

     • Delete the group

       Important

       • A user whose role is "admin" does not automatically have the permissions of a group administrator or creator.

       • Only the group creator or an administrator can perform the preceding operations. A user who is not the creator or an administrator of the group cannot modify the group, mute members, or delete the group.