This API is used by the app admin to create groups.
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. |
Community | 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 joinAVChatRoom
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.
https://xxxxxx/v4/group_open_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
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 |
---|---|
https | The request protocol is HTTPS, and the request method is POST. |
xxxxxx | The country/region where your SDKAppID is located.console.tim.qq.com adminapisgp.im.qcloud.com adminapikr.im.qcloud.com adminapiger.im.qcloud.com adminapiind.im.qcloud.com |
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. |
contenttype | Request format. The value is always json . |
The maximum calling frequency is 200 calls per second.
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)
}
{
"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)
}
{
"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 100 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"
}
]
}
{
"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)
}
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.
}
]
}
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"
}
]
}
]
}
{
"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 100 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"
}
]
}
]
}
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 100 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. |
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"
}
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. |
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 100. 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. |
Use the online debugging tool for RESTful APIs to debug this API.
Was this page helpful?