Creating a Group

Feature Description

The app admin can create groups through this API.

API Invocation Description

Applicable group types

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.

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

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

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.

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

• Callback before creating a group
• Callback after creating a group