Creating a Group

Last updated: 2020-07-06 16:40:40

    Feature Description

    This API is used by the app admin to create groups.

    API Calling Description

    Applicable group types

    Group Type ID Is this RESTful API Supported?
    Private Yes. Same as Work (work group for friends) in the new version.
    Public Yes.
    ChatRoom Yes. Same as Meeting (temporary meeting group) in the new version.
    AVChatRoom Yes.

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

    • If the group type is specified as AVChatRoom:
      • The number of groups that can be created varies depending on the actual package. For more information, see Pricing.
      • Inviting users to groups is not supported when AVChatRoom groups are created, and a 10007 error will be returned if users to invite are specified during creation. The only way for users to join AVChatRoom groups is to apply.
    • If the group type is specified as a type other than AVChatRoom:
      • If neither a group owner nor a group member list is specified when the request is sent, the number of groups that can be created is unrestricted.
      • If a group owner or group member list is specified when the request is sent, the specified group owner or group members are automatically added to the group.
    • If the total number of groups in the app exceeds 100,000, certain fees will be charged. For more information, see Pricing.
    • A user account can only join a limited number of groups. Therefore, when that limit is exceeded, joining or creating groups will fail. For more information, see Pricing.

    Sample request URL

    https://console.tim.qq.com/v4/group_open_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

    Request parameters

    The list below contains only the parameters commonly used when calling this API and their descriptions. For more parameters, see RESTful API Overview.

    Parameter Description
    v4/group_open_http_svc/create_group Request API
    sdkappid SDKAppID assigned by the IM console when the application is created
    identifier The value must be the app admin account. For more information, see App Admins.
    usersig Signature generated by the app admin account. For details, see Generating UserSig.
    random A random 32-bit unsigned integer ranging from 0 to 4294967295

    Maximum calling frequency

    The maximum calling frequency is 200 calls per second.

    Sample request packet

    • Basic form
      Create a group. The Owner_Account field is optional. If the parameter is not specified, the group will have no group owner.

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private/Public/ChatRoom/AVChatRoom/BChatRoom (required)
        "Name": "TestGroup" // Group name (required)
      }
    • Only contains basic group information
      Create a group and specify basic group information, such as the group introduction and group announcement.

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private/Public/ChatRoom/AVChatRoom/BChatRoom (required)
        "Name": "TestGroup", // Group name (required)
        "Introduction": "This is group Introduction", // Group introduction (optional)
        "Notification": "This is group Notification", // Group announcement (optional)
        "FaceUrl": "http://this.is.face.url", // Group profile photo URL (optional)
        "MaxMemberCount": 500, // Maximum number of group members (optional)
        "ApplyJoinOption": "FreeAccess"  // Method for handling requests to join the group (optional)
      }
    • Only contains group member information
      Create a group and specify the initial group member list. The group member list is described in the request packet description table.

      {
        "Name": "TestGroup", // Group name (required)
        "Type": "Public", // Group type: Private/Public/ChatRoom (AVChatRoom and BChatRoom are not supported) (required)
        "MemberList": [ // Initial group member list, which contains a maximum of 500 members (optional)
             {
                "Member_Account": "bob", // Member (required)
                "Role": "Admin" // Role assigned to the member (optional). Currently, only the Admin option is available.
             },
             {
                "Member_Account": "peter"
             }
         ]
      }
    • Custom group ID
      To simplify group IDs, Tencent Cloud allows apps to customize group IDs when creating groups through the RESTful API.

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private/Public/ChatRoom/AVChatRoom/BChatRoom (required)
        "GroupId": "MyFirstGroup", // User-defined group ID (optional)
        "Name": "TestGroup"   // Group name (required)
      }
    • Only contains custom group information
      Create a group and specify group custom fields. By default, AppDefineData is not available, so it needs to be enabled before use. For details, see the request packet field description table.

      {
        "Name": "TestGroup", // Group name (required)
        "Type": "Public", // Group type: Private/Public/ChatRoom/AVChatRoom/BChatRoom (required)
        "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.
            }
        ]
      }
    • Only contains custom group member information
      Create a group and specify group member custom fields. By default, AppMemberDefinedData is not available, so it needs to be enabled before use. For details, see the table for request packet fields.

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private/Public/ChatRoom (AVChatRoom and BChatRoom are not supported) (required)
        "Name": "TestGroup", // Group name (required)
        "MemberList": [
           {
              "Member_Account":"bob",
              "AppMemberDefinedData":[ // Group member custom field (optional)
                   {
                       "Key": "MemberDefined1", // Group member custom key
                       "Value": "MemberData1" // Value of the group member custom field
                   },
                   {
                       "Key": "MemberDefined2",
                       "Value": "MemberData2"
                   }
               ]
           },
           {
              "Member_Account":"peter",
              "AppMemberDefinedData":[
                   {
                       "Key": "MemberDefined1",
                       "Value": "MemberData1"
                   },
                   {
                       "Key": "MemberDefined2",
                       "Value": "MemberData2"
                   }
               ]
           }
        ]
      }
    • ALL IN ONE

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private/Public/ChatRoom (AVChatRoom and BChatRoom are not supported) (required)
        "GroupId":"MyFirstGroup", // User-defined group ID (optional)
        "Name": "TestGroup", // Group name (required)
        "Introduction": "This is group Introduction", // Group introduction (optional)
        "Notification": "This is group Notification", // Group announcement (optional)
        "FaceUrl": "http://this.is.face.url", // Group profile photo URL (optional)
        "MaxMemberCount": 500, // Maximum number of group members (optional)
        "ApplyJoinOption": "FreeAccess", // Method for handling requests to join the group (optional)
        "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.
            }
        ],
        "MemberList": [ // Initial group member list, which contains a maximum of 500 members (optional)
            {
                "Member_Account": "bob", // Member (required)
                "Role": "Admin", // Role assigned to the member. Currently, only the Admin option is available. (optional)
                "AppMemberDefinedData":[ // Group member custom field (optional)
                   {
                       "Key":"MemberDefined1", // Group member custom key
                       "Value":"MemberData1" // Value of the group member custom field
                   },
                   {
                       "Key":"MemberDefined2",
                       "Value":"MemberData2"
                   }
               ]
            },
            {
                "Member_Account": "peter",
                "AppMemberDefinedData":[
                   {
                       "Key":"MemberDefined1",
                       "Value":"MemberData1"
                   },
                   {
                       "Key":"MemberDefined2",
                       "Value":"MemberData2"
                   }
               ]
            }
        ]
      }

    Request packet fields

    Field Type Property Description
    Owner_Account String Optional Group owner ID, which will be automatically added to group members. If this parameter is not specified, the group will have no group owner.
    Type String Required Possible group types are Public (social networking group for strangers), Private (work group for friends, same as Work), ChatRoom (meeting group, same as Meeting), and AVChatRoom (live streaming group).
    GroupId String Optional To simplify group IDs and make them easier to remember and propagate, Tencent Cloud allows apps to customize group IDs when creating groups through the RESTful API.
    Name String Required Group name, whose maximum length is 30 bytes. This parameter is UTF-8-encoded, and one Chinese character occupies 3 bytes.
    Introduction String Optional Group introduction, whose maximum length is 240 bytes. This parameter is UTF-8-encoded, and one Chinese character occupies 3 bytes.
    Notification String Optional Group announcement, whose maximum length is 300 bytes. This parameter is UTF-8-encoded, and one Chinese character occupies 3 bytes.
    FaceUrl String Optional URL of the group profile photo, whose maximum length is 100 bytes
    MaxMemberCount Integer Optional Maximum number of group members. Default values: Private: 200, Public: 2000, ChatRoom: 6000, AVChatRoom and BChatRoom: no limit.
    ApplyJoinOption String Optional Method for handling requests to join the group, which can be FreeAccess, NeedPermission, or DisableApply. The default method is NeedPermission.
    This parameter is valid only for groups that can be joined by users.
    AppDefinedData Array Optional Group-level custom field. By default, this parameter is not available and needs to be enabled. For details, see Custom Fields.
    MemberList Array Optional Initial group member list, which contains a maximum of 500 members. For details on group member information fields, see Group Member Profiles.
    AppMemberDefinedData Array Optional Group member custom fields. By default, this parameter is not available and needs to be enabled. For details, see Custom Fields.

    Sample response packet body

    • Basic form, only contains basic group information, only contains group member information, and only contain customs information
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "GroupId": "@TGS#2J4SZEAEL"
      }
    • Custom group ID and ALL IN ONE
      {
        "ActionStatus": "OK",
        "ErrorInfo": "",
        "ErrorCode": 0,
        "GroupId": "MyFirstGroup"
      }

    Response packet fields

    Field Type Description
    ActionStatus String Result of the request. OK indicates that the request was successful, and FAIL indicates that the request failed.
    ErrorCode Integer Error code. 0 indicates that the request was successful, and any non-zero value indicates that the request failed.
    ErrorInfo String Detailed error information
    GroupId String Resulting group ID after successful creation, which is assigned by the IM backend.

    Error Codes

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

    Error Code Description
    10002 An internal server error occurred. Please try again.
    10003 The request command word is invalid.
    10004 A parameter is invalid. Check the error description and troubleshoot the issue.
    10005 The number of members imported in the request packet exceeds 500. Reduce the number of members imported in the MemberList parameter.
    10006 The number of groups created exceeds the quota. For example, the cumulative number of BChatRoom groups created exceeds 5, or the net increase in the number of groups in a single day exceeds the set quota. For details, see Differences in Group Limits.
    10007 The operation permissions are insufficient. Check the request parameters based on the error information. For example, the specified group type does not allow adding members, but you specified MemberList in the request packet.
    10008 The request is invalid, probably because verification of the signing information in the request failed. Please try again or submit a ticket to contact technical support.
    10016 The app backend rejected this operation through a third-party callback. Check the returned value of your callback service "Callback before creating a group".
    10021 The group ID has already been used by another user. Select another group ID.
    10025 You have already used this group ID. Disband the existing group first or select another group ID.
    10036 The number of AVChatRoom groups created exceeds the limit. Disband some AVChatRoom groups first or refer to Pricing to purchase an upgrade.
    10037 The request specifies Owner_Account, but the number of groups that the group owner has created or joined exceeds the limit. The group owner needs to quit some groups first or refer to Pricing to purchase an upgrade.
    10038 The number of members imported in the request packet exceeds the limit. Reduce the number of members imported in the MemberList parameter or refer to Pricing to purchase an upgrade.
    80001 The group failed text content filtering. Check whether the group name, group announcement, group introduction, or other content contains sensitive words.

    API Debugging Tool

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

    Reference

    Possible Callbacks

    Was this page helpful?

    Was this page helpful?

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