tencent cloud


Importing a Group Profile

Last updated: 2022-07-06 16:44:57


    This API allows the app admin to import group data without triggering callbacks or delivering notifications. When your app needs to be migrated to Instant Messaging (IM) from another instant messaging system, you can use this API to import existing group data.

    API Calling Description

    Applicable group types

    Group Type ID Support for This RESTful API
    Private Yes. Same as work groups (Work) in the new version.
    Public Yes
    ChatRoom Yes. Same as meeting groups (Meeting) in the new version.
    AVChatRoom No
    Community Yes

    Above are the built-in group types of IM. For more information, see Group System.


    AVChatRoom groups do not support importing basic group data. If you attempt to import basic group data for AVChatRoom groups, error 10007 is returned. To achieve the effect of importing basic group data, you can create a group and modify basic group data.

    Sample request URL


    Request parameters

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

    Parameter Description
    xxxxxx The country/region where your SDKAppID is located.
  • China: console.tim.qq.com
  • Singapore: adminapisgp.im.qcloud.com
  • Seoul: adminapikr.im.qcloud.com
  • Frankfurt: adminapiger.im.qcloud.com
  • India: adminapiind.im.qcloud.com
  • v4/group_open_http_svc/import_group Request API
    sdkappid SDKAppID assigned by the IM console when an app is created
    identifier App admin account. For more information, see the App Admin section in Login Authentication.
    usersig Signature generated by the app admin account. For operation details, see Generating UserSig.
    random A random 32-bit unsigned integer ranging from 0 to 4,294,967,295
    contenttype Request format, which should always be json.

    Maximum call frequency

    200 calls per second

    Sample request

    • Basic format
      Import a group. You can use CreateTime to specify the group creation time.

       "Owner_Account": "leckie", // UserId of the group owner (optional)
       "Type": "Public", // Group type: Private, Public, ChatRoom, or Community (required)
       "Name": "TestGroup", // Group name (required)
       "CreateTime": 1448357837 // Group creation time (optional). If this field is not specified, the default creation time is the request time.
    • Specifying other optional fields
      You can specify optional fields such as Introduction and Notice. The request format is the same as that of a group creation request.

       "Owner_Account": "leckie", // UserId of the group owner (optional)
       "Type": "Public", // Group type: Private, Public, ChatRoom, or Community (required)
       "GroupId":"MyFirstGroup", // User-defined group ID for external display (optional)
       "Name": "TestGroup", // Group name (required)
       "Introduction": "This is group Introduction", // Group introduction (optional)
       "Notification": "This is group Notification", // Group notice (optional)
       "FaceUrl": "http://this.is.face.url",
       "MaxMemberCount": 500, // Maximum number of group members (optional)
       "ApplyJoinOption": "FreeAccess", // Method for handling requests to join the group (optional)
       "CreateTime": 1448357837, // Group creation time (optional). If this field is not specified, the default creation time is the request time.
       "AppDefinedData": [ // Group custom field (optional)
               "Key": "GroupTestData1", // Key of the app custom field
               "Value": "xxxxx" // Value of the custom field
               "Key": " GroupTestData2",
               "Value": "abc\u0000\u0001" // The custom field supports binary data.

    Request fields

    Field Type Required Description
    Owner_Account String Optional Group owner ID, which will be automatically added to group members. If this field is not specified, the group will have no group owner.
    Type String Required Group type, which can be Public, Private (Work), ChatRoom, or Community.
    GroupId String Optional To simplify group IDs and make them easy to remember, Tencent Cloud allows apps to customize group IDs during group creation through RESTful APIs. For details, see Group Systems.
    Name String Required Group name, whose maximum length is 30 bytes.
    Introduction String Optional Group introduction, whose maximum length is 240 bytes.
    Notification String Optional Group notice, whose maximum length is 300 bytes.
    FaceUrl String Optional URL of the group profile photo, whose maximum length is 100 bytes.
    MaxMemberCount Integer Optional Maximum number of group members, which is 6,000 at the maximum. The default value is 2,000.
    ApplyJoinOption String Optional Method for handling requests to join the group. Valid values: FreeAccess, NeedPermission (default), and DisableApply.
    AppDefinedData Array Optional Group custom field. By default, this field is unavailable and needs to be enabled before use. For details, see Group Systems.
    CreateTime Integer Optional Group creation time

    Sample response

    • Basic format
       "ActionStatus": "OK",
       "ErrorInfo": "",
       "ErrorCode": 0,
       "GroupId": "@TGS#2J4SZEAEL"
    • Specifying other optional fields
       "ActionStatus": "OK",
       "ErrorInfo": "",
       "ErrorCode": 0,
       "GroupId": "MyFirstGroup"

    Response fields

    Field Type Description
    ActionStatus String Request result. OK: Successful; FAIL: Failed
    ErrorCode Integer Error code. 0: Successful; other values: Failed
    ErrorInfo String Error information
    GroupId String Group ID after successful creation, which is assigned by the IM backend or specified by users.

    Error Codes

    The returned HTTP status code for this API is always 200 unless a network error (such as error 502) occurs. The specific error code and details can be found in the response fields ErrorCode and ErrorInfo respectively.
    For public error codes (60000 to 79999), see Error Codes.
    The following table describes the error codes specific to this API:

    Error Code Description
    10002 Internal server error. Try again.
    10003 Invalid command word.
    10004 Invalid parameter. Check the error description and troubleshoot the issue.
    10007 No operation permissions. This error occurs when, for example, a member in a public group tries to remove other users from the group (only the app admin can perform this operation).
    10021 The group ID is already in use. Specify another group ID.

    API Debugging Tool

    Use the RESTful API online debugging tool to debug this API.


    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support