Creating a Group

Last updated: 2020-05-14 18:28:55

PDF

Feature Description

The app admin can create groups through this API.

API Invocation Description

Applicable group types

Group Type Support This RESTful API
Private Yes
Public Yes
ChatRoom Yes
AVChatRoom Yes
BChatRoom Yes

IM supports the preceding five types of groups. For details, see Group Systems.

  • If the group type is set to AVChatRoom, for details on the number of groups that can be created, see Pricing.
  • If the group type is set to BChatRoom, the number of groups that can be created is 5. For details, see Differences in Group Limits.
  • If the group type is set to Private, Public, or ChatRoom:
  • If the request does not specify the group owner nor set the group member list, no limit is applied to the number of groups that can be created. However, if the total number of groups in the app exceeds 100,000, you must pay a certain fee for excessive groups.
  • If the request specifies the group owner or sets the group member list, the specified group owner or members will be automatically added to the group. As the number of groups that an ordinary account can join is limited, the number of groups that can be created in such cases is also limited. For details, see Pricing.
  • When creating an AVChatRoom or BChatRoom group, you cannot add members to the group. If you specify group members during the creation, error 10007 returns. The only way for users to join an AVChatRoom or BChatRoom group is to raise an application.

Request URL example

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 following table lists and describes only the parameters to be modified when this API is invoked. For details on other parameters, see RESTful API Overview.

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

Maximum invocation frequency

The maximum invocation frequency is 200 times per second.

Request packet examples

  • Basic format
    Create a group, and the Owner_Account field is optional. If this parameter is not specified, the group has no group owner.

    {
      "Owner_Account": "leckie", // Group owner’s UserId (optional)
      "Type": "Public", // Group type: Private, Public, ChatRoom, AVChatRoom, or BChatRoom (required)
      "Name": "TestGroup" // Group name (required)
    }
  • Containing only basic group information
    Create a group and specify basic group information, such as group introduction and group announcements.

    {
      "Owner_Account": "leckie", // Group owner’s UserId (optional)
      "Type": "Public", // Group type: Private, Public, ChatRoom, AVChatRoom, or 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, // Max number of group members (optional)
      "ApplyJoinOption": "FreeAccess"  // Method for handling group requests
    }
  • Containing only 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, or ChatRoom (AVChatRoom and BChatRoom are not supported) (required)
      "MemberList": [ // Initial group member list with a maximum of 500 members (optional)
           {
              "Member_Account": "bob", // Member (required)
              "Role": "Admin" // Assigned role of the member. Currently, Admin is the only choice. (optional)
           },
           {
              "Member_Account": "peter"
           }
       ]
    }
  • Customizing group IDs
    To simplify group IDs, Tencent Cloud allows apps to customize group IDs when creating groups through the RESTful API.

    {
      "Owner_Account": "leckie", // Group owner’s UserId (optional)
      "Type": "Public", // Group type: Private, Public, ChatRoom, AVChatRoom, or BChatRoom (required)
      "GroupId": "MyFirstGroup", // User-defined group ID (optional)
      "Name": "TestGroup"   // Group name (required)
    }
  • Containing only custom group information
    Create a group and specify group custom fields. By default, AppDefineData is unavailable, which therefore needs to be enabled. For details, see the description table of request packet fields.

    {
      "Name": "TestGroup", // Group name (required)
      "Type": "Public", // Group type: Private, Public, ChatRoom, AVChatRoom, or BChatRoom (required)
      "AppDefinedData": [ // Group custom field (optional)
          {
              "Key": "GroupTestData1", // App custom field Key
              "Value": "xxxxx" // Value of the custom field
          },
          {
              "Key": " GroupTestData2",
              "Value": "abc\u0000\u0001" // Value of another custom field that supports binary data
          }
      ]
    }
  • Containing only custom group member information
    Create a group and specify group member custom fields. By default, AppMemberDefinedData is unavailable, which therefore needs to be enabled for use. For details, see Request packet fields.

    {
      "Owner_Account": "leckie", // Group owner’s UserId (optional)
      "Type": "Public", // Group type: Private, Public, or 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 field 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", // Group owner’s UserId (optional)
      "Type": "Public", // Group type: Private, Public, or 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 group requests (optional)
      "AppDefinedData": [ // Group custom fields (optional)
          {
              "Key": "GroupTestData1", // App custom field Key
              "Value": "xxxxx" // Value of the custom field
          },
          {
              "Key": "GroupTestData2",
              "Value": "abc\u0000\u0001" // Value of another custom field that supports binary data
          }
      ],
      "MemberList": [ // Initial group member list with a maximum of 500 members (optional)
          {
              "Member_Account": "bob", // Member (required)
              "Role": "Admin", // Assigned role of the member. Currently, Admin is the only choice. (optional)
              "AppMemberDefinedData":[ // Group member custom fields (optional)
                 {
                     "Key":"MemberDefined1", // Group member custom field 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 Attribute Description
Owner_Account String Optional The group owner ID, which will be automatically added to group members. If this field is not specified, the group has no group owner.
Type String Required The group type, which can be Public, Private, ChatRoom, AVChatRoom, or BChatRoom.
GroupId String Optional To simplify group IDs and make them memorable and propagatable, Tencent Cloud allows apps to customize group IDs when creating groups through the RESTful API.
Name String Required The group name with a maximum length of 30 bytes. It is encoded in UIT-8, and 1 Chinese character occupies 3 bytes.
Introduction String Optional The group introduction with a maximum length of 240 bytes. It is encoded in UIT-8, and one Chinese character occupies 3 bytes.
Notification String Optional The group announcement with a maximum length of 300 bytes. It is encoded in UIT-8, and one Chinese character occupies 3 bytes.
FaceUrl String Optional The group profile photo URL with a maximum length of 100 bytes.
MaxMemberCount Integer Optional The maximum number of group members. Default values: Private: 200, Public: 2000, ChatRoom: 6000, AVChatRoom and BChatRoom: unlimited.
ApplyJoinOption String Optional The method for handling group requests, which can be FreeAccess (unrestricted), NeedPermission (approval required), or DisableApply (denied). The default method is NeedPermission if this field is not specified.
This field is valid only for creating groups that allow joining.
AppDefinedData Array Optional Group custom fields. By default, this field is unavailable and needs to be enabled for use. For details, see Custom Fields.
MemberList Array Optional The initial group member list with maximum 500 members. For details on group member information fields, see Group Member Profiles.
AppMemberDefinedData Array Optional Group member custom fields. By default, this field is unavailable and needs to be enabled for use. For details, see Custom Fields.

Response packet example

  • Basic format, containing only basic group information, containing only group member information, and containing only 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 The request processing result. OK: succeeded. FAIL: failed.
ErrorCode Integer The error code. 0: succeeded. Others: failed.
ErrorInfo String The error information.
GroupId String The group ID after successful creation, which is assigned by the IM backend.

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, respectively.
For common error codes (60000 to 79999), see Error Codes.
The following table describes the error codes specific to this API.

Error Code Description
10002 A server internal error occurred. In this case, try again.
10003 A request command keyword is invalid.
10004 A parameter is invalid. In this case, check whether request parameters are correct based on the error description.
10005 The number of members imported into the request packet exceeds 500. In this case, reduce the number of imported members in the MemberList parameter.
10006 The number of created groups exceeds the limit. For example, the cumulative number of created BChatRooms groups 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 Operation permissions are insufficient. In this case, check request parameters based on the error information. For example, the specified group type disallows you to add members, but you specified MemberList in the request packet.
10008 The request is invalid. This error occurs when the signature information in the request is incorrect. In this case, try again or submit a ticket to contact our technical support service.
10016 The app backend denies this operation through a third-party callback. In this case, check the returned value of your callback service "Callback before creating a group".
10021 The group ID has already been used by another user. In this case, select another group ID.
10025 You have used this group ID. In this case, dismiss the group first or select another group ID.
10036 The number of created AVChatRoom groups exceeds the limit. In this case, dismiss some AVChatRoom groups first or purchase an upgraded quota by referring to Pricing.
10037 The request specifies Owner_Account, but the number of groups that the group owner has created or joined exceeds the limit. In this case, the group owner needs to quit some groups first or purchase an upgraded quota by referring to Pricing.
10038 The number of members imported into the request packet exceeds the limit. In this case, reduce the number of imported members in the MemberList parameter or purchase an upgraded quota by referring to Pricing.
80001 The group fails to pass the text security verification. In this case, check whether the group name, group announcement, group introduction, or another content contains sensitive words.

API Commissioning Tool

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

References

Dismissing a group (v4/group_open_http_svc/destroy_group)

Callbacks That Can Be Triggered