Creating a Group

Last updated: 2021-01-25 16:05:44

    Feature Description

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

    API Calling Description

    Applicable group types

    Group Type ID RESTful API Support
    Private Yes. Same as Work (work group) in the new version.
    Public Yes.
    ChatRoom Yes. Same as Meeting (temporary meeting group) in the new version.
    AVChatRoom Yes.

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

    Note:

    • 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 Introduction.

    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 the App Admin section in Login Authentication.
    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
        "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
        "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 is 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 (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. AppDefineData is not available by default and needs to be enabled in the IM console before use. For details, see the description table for request packet fields.

      {
        "Name": "TestGroup", // Group name (required)
        "Type": "Public", // Group type: Private, Public, ChatRoom, AVChatRoom (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. AppMemberDefinedData is not available by default and needs to be enabled in the IM console before use. For details, see the description table for request packet fields.

      {
        "Owner_Account": "leckie", // UserId of the group owner (optional)
        "Type": "Public", // Group type: Private, Public, ChatRoom (AVChatRoom is 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 is 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 Required 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 (audio-video 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: 200 for Private, 2000 for Public, 6000 for ChatRoom, and no limit for AVChatRoom and BChatRoom.
    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 custom field. This parameter is not available by default and needs to be enabled in the IM console. 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. This parameter is not available by default and needs to be enabled in the IM console. For details, see Custom Fields.

    Sample response packet body

    • Basic form, only contains basic group information, only contains group member information, and only contains custom 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 Processing result of the request. OK: succeeded. FAIL: failed.
    ErrorCode Integer Error code. 0: succeeded. Other values: 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 ErrorCode and ErrorInfo respectively.
    For public error codes (60000 to 79999), see Error Codes.
    The list below contains error codes specific to this API.

    Error Code Description
    10002 Internal server error. Please try again.
    10003 Invalid request command word.
    10004 Invalid parameter. Check the error description and troubleshoot the issue.
    10005 The number of members imported in the request packet exceeds 300. 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 Insufficient permissions. 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.
    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. Delete the existing group first or select another group ID.
    10036 The number of AVChatRoom groups created exceeds the limit. Delete 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 information 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