Feature Description

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

API Calling Description

Applicable group types

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.

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

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

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.

API Debugging Tool

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

Reference

• Deleting a group (v4/group_open_http_svc/destroy_group)

Possible Callbacks

• Callback Before Creating a Group
• Callback After Creating a Group