tencent cloud

Feature Description

This API is used by the app admin to query detailed group information based on the group ID.

Call Description

Applicable group types

These are the 4 built-in group types in IM. For detailed information, see the Group System.

Example request URL

https://xxxxxx/v4/group_open_http_svc/get_group_info?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table only describes the parameters that are modified when this API is called. For more information on other parameters, see RESTful API Overview.

Maximum call frequency

200 times/second

Example request packet

• Basic form
  The following example is used to obtain the detailed group information, including all the basic group information, group member information, and custom information. The request only contains a list of group IDs. Each request can be used to query information on a maximum of 50 groups.

  {
   "GroupIdList": [ // Group ID list (required)
       "@TGS#1NVTZEAE4",
       "@TGS#1CXTZEAET"
   ]
  }
  

• Pulling specified information

  • To specify the basic information fields to be pulled, set GroupBaseInfoFilter.
  • To specify the member information fields to be pulled, set MemberInfoFilter.
  • To specify the group-specific custom fields to be pulled, set AppDefinedDataFilter_Group. This field is unavailable by default and must be enabled additionally. For more information, see "Request packet fields".
  • To specify the group member-specific custom fields to be pulled, set AppDefinedDataFilter_GroupMember. This field is unavailable by default and must be enabled additionally. For more information, see "Request packet fields".

  If filters are set, only the fields specified by filters are pulled.

  {
   "GroupIdList": [ // Group ID list (required)
       "@TGS#1NVTZEAE4",
       "@TGS#1CXTZEAET"
   ],
   "ResponseFilter": { // The filters that you specify for the response.
       "GroupBaseInfoFilter": [ // Add this array if you want to query the basic information.
           "Type",
           "Name",
           "Introduction",
           "Notification"
       ],
       "MemberInfoFilter": [ // Add this array if you want to query the member information.
           "Account", // Member ID
           Role
       ],
       "AppDefinedDataFilter_Group": [ // The filter for group-specific custom fields. This filter is disabled by default.
           "GroupTestData1",
           "GroupTestData2"
       ],
       "AppDefinedDataFilter_GroupMember": [ // The filter for group member-specific custom fields. This filter is disabled by default.
           "MemberDefined2",
           "MemberDefined1"
       ]
   }
  }
  

Request packet fields

Example response packet body

• Basic form

  {
   "ActionStatus":"OK",
   "ErrorInfo": "", // The ErrorInfo parameter here is meaningless. You need to check the ErrorInfo parameter of each group.
   "ErrorCode": 0, // The ErrorCode parameter here is meaningless. You need to check the ErrorCode parameter of each group.
   "GroupInfo": [ // A group information array is returned. Only one group is listed here for simplicity.
       {
           "GroupId": "@TGS#2J4SZEAEL",
           "ErrorCode": 0, // The result specific to this group.
           "ErrorInfo": "" , // The result specific to this group.
           "Type": "Public", // The group type.
           "Name": "MyFirstGroup", // The group name.
           "Appid":1400001001,// The SDKAppID of the IM application.
           "Introduction": "TestGroup", // Group introduction.
           "Notification": "TestGroup", // Group notification.
           "FaceUrl": "http://this.is.face.url", // The group profile photo.
           "Owner_Account": "leckie", // The group owner ID.
           "CreateTime": 1426976500, // The group creation time in UTC.
           "LastInfoTime": 1426976500, // The UTC time when the group information was last updated.
           "LastMsgTime": 1426976600, // The UTC time when the last message in the group was sent.
           "NextMsgSeq": 1234,
           "MemberNum": 2, // The current number of members in the group.
           "MaxMemberNum": 50, // The maximum number of members in the group.
           "ApplyJoinOption": "FreeAccess", // The method for handling requests to join the group.
           "ShutUpAllMember": "On", // All members in the group are muted.
           "AppDefinedData": [ // Group-specific custom fields.
               {
                   "Key": "GroupTestData1", // Key of the custom field.
                   "Value": "xxxx" // Value of the custom field.
               },
               {
                   "Key": "GroupTestData2",
                   "Value": "abc\u0000\u0001" // Custom fields support binary data.
               }
           ],
           "MemberList": [ // The group member list.
               {
                   "Member_Account": "leckie", // The member ID.
                   "Role": "Owner", // The role of the member in the group.
                   "JoinTime": 1425976500, // The UTC time when the member joined the group.
                   "MsgSeq": 1233,
                   "MsgFlag": "AcceptAndNotify", // Indicates whether the member blocks group messages.
                   "LastSendMsgTime": 1425976500, // The last time in UTC when the member sent a message in the group.
                   "ShutUpUntil": 1431069882, // The UTC time when the muting period for the member expires.
                   "AppMemberDefinedData": [ // Group member-specific custom fields.
                       {
                            "Key": "MemberDefined1",
                            "Value": "ModifyDefined1"
                       },
                       {
                            "Key": "MemberDefined2",
                            "Value": "ModifyDefined2"
                       }
                   ]
               },
               {
                   "Member_Account": "peter",
                   "Role": "Member",
                   "JoinTime": 1425976500, // The time when the member joined the group.
                   "MsgSeq": 1233,
                   "MsgFlag": "AcceptAndNotify",
                   "LastSendMsgTime": 1425976500, // The last time when the member sent a message.
                   "ShutUpUntil": 0, // The value 0 indicates that the member is not muted, and other values indicate the time when the member will be unmuted.
                   "AppMemberDefinedData":[ // Group member-specific custom fields.
                       {
                           "Key": "MemberDefined1",
                           "Value": "ModifyDefined1"
                       },
                       {
                           "Key": "MemberDefined2",
                           "Value": "ModifyDefined2"
                       }
                    ]
               }
           ]
       }
   ]
  }
  

• Pulling specified information

  {
   "ActionStatus": "OK",
   "ErrorInfo": "", // The ErrorInfo parameter here is meaningless. You need to check the ErrorInfo parameter of each group.
   "ErrorCode": 0, // The ErrorCode parameter here is meaningless. You need to check the ErrorCode parameter of each group.
   "GroupInfo": [ // A group information array is returned. Only one group is listed here for simplicity.
       {
           "GroupId": "@TGS#2J4SZEAEL",
           "ErrorCode": 0, // The result specific to this group.
           "ErrorInfo":"" , // The result specific to this group.
           "Type": "Public", // The group type.
           "Name": "MyFirstGroup", // The group name.
           "Introduction": "TestGroup", // Group introduction.
           "Notification": "TestGroup", // Group notification.
           "AppDefinedData": [ // Group-specific custom fields.
               {
                   "Key": "GroupTestData1", // Key of the custom field.
                   "Value": "xxxx" // Value of the custom field.
               },
               {
                   "Key": "GroupTestData2",
                   "Value": "abc\u0000\u0001" // Custom fields support binary data.
               }
           ],
           "MemberList": [ // The group member list.
               {
                   "Member_Account": "leckie", // The member ID.
                   "Role": "Owner", // The role of the member in the group.
                   "AppMemberDefinedData":[ // Group member-specific custom fields.
                       {
                           "Key":" MemberDefined1",
                           "Value":" ModifyDefined1"
                       },
                       {
                           "Key":" MemberDefined2",
                           "Value":" ModifyDefined2"
                       }
                    ]
               },
               {
                   "Member_Account": "peter",
                   "Role": "Member",
                   "AppMemberDefinedData":[ // Group member-specific custom fields.
                       {
                           "Key":" MemberDefined1",
                           "Value":" ModifyDefined1"
                       },
                       {
                           "Key":" MemberDefined2",
                           "Value":" ModifyDefined2"
                       }
                    ]
               }
           ]
       }
   ]
  }
  

Response packet fields

Error Codes

Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information.
For public error codes 60000 to 79999, see Error Codes.
The following table describes the error codes specific to this API.

Commissioning Tool

Use the RESTful API online commissioning tool to commission this API.

References

• Obtaining detailed information on group members (v4/group_open_http_svc/get_group_member_info)
• Modifying basic group information (v4/group_open_http_svc/modify_group_base_info)
• Modifying information on group members (v4/group_open_http_svc/modify_group_member_info)