Create Group

Last updated:2025-03-31 20:06:44

Create Group

Last updated: 2025-03-31 20:06:44

API Call Description
Use this API to create a group with a customer service account. Inquiries to this account are directly transferred to an agent. If no agent is online, the API returns a failure response.
API Request Limitation
Before calling this API, please first contact us to enable the customer service group chat feature.
This API can only be called by Desk trial and premium package.
Currently only support creating a group with one customer service account. At the time of creation, the initial member list must be specified, which must include at least one non-customer service account member.
After creating group, newly invited customer service accounts don't support live transfer.
This API only supports creating groups of type Private and Public.
Sample Request URL
https://console.tim.qq.com/v4/desk_http_svc/create_group?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json
Request Parameters
The following table only lists the parameters involved in modification when calling this API and their descriptions. For more parameter details, please see REST API Introduction.
Parameter
Description
v4/desk_http_svc/create_group
Request API.
sdkappid
Assigned SDKAppID in the Chat console when creating an application.
identifier
Must be an App administrator account. For more details, see App Administrator.
usersig
Generated signature of the App administrator account. For specific operations, see Generate UserSig.
random
Enter a random 32-bit unsigned integer. The value ranges from 0 to 4294967295.
contenttype
The request format has a fixed value of json.
Sample Request Packet
{
  "Owner_Account": "user3", // Group owner's UserId (optional)
  "Type": "Public", // Group type: Private/Public (required)
  "GroupId":"MyFirstGroup", // Custom Group ID (required)
  "Name": "TestGroup", // Group name (required)
  "Introduction": "This is group introduction", // Group introduction (optional)
  "Notification": "This is group notice", // Group notice (optional)
  "FaceUrl": "http://this.is.face.url", // Group Avatar URL (optional)
  "MaxMemberCount": 500, // Maximum number of group members (optional)
  "ApplyJoinOption": "FreeAccess", // Method of handling request to join group (optional)
  "MemberList": [ // Initial group member list, up to 100 (optional)
      {
          "Member_Account": "user2", // Member (required)
          "Role": "Admin" // The identity assigned to this member, currently the only option is Admin (optional).
      },
      {
          "Member_Account": "@customer_service_account"
      }
  ]
}
Request Packet Fields
Field
Type
Required
Description
Owner_Account
String
Optional.
Group Owner ID (must be an imported account). After filling in, it will be automatically added to the group members; if left empty, the group will have no group owner.
Type
String
Required
GroupType, including Public (stranger social group), Private (i.e., Work, work group).
GroupId
String
Required
To make the group ID simpler and easier to remember and spread, tencent cloud support allows apps to customize group ID when creating a group via REST API.
Name
String
Required
Group name, up to 100 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
Introduction
String
Optional.
Group introduction, up to 400 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
Notification
String
Optional.
Group notice, up to 400 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
FaceUrl
String
Optional.
Group Avatar URL, up to 500 bytes.
MaxMemberCount
Integer
Optional.
The maximum number of group members. By default, it is the paid package upper limit. For example, it is 20 for the trial version. If you upgrade the package, you need to modify this field by modifying group basic information.
ApplyJoinOption
String
Optional.
Method of handling request to join group. Options include FreeAccess (free joining), NeedPermission (approval required), DisableApply (group join prohibition). If not filled in, the specific default value can be seen in Differences in group joining methods.
this field is valid only when creating a group that supports initiation request to join.
InviteJoinOption
String
Optional.
Method for handling invitations to join the group, including FreeAccess (directly invite users to the group without approval and other operations), NeedPermission (requiring approval from the group admin or owner), DisableInvite (unsupported SDK invitation to join the group). This option is not supported by the AVChatRoom group type.
AppDefinedData
Array
Optional.
Custom fields at the group dimension are not available by default. They can be configured through Chat Console. For details, see Custom Fields.
MemberList
Array
Required
Initial group member list, up to 100; for details on member information fields, see group member profile.
AppMemberDefinedData
Array
Optional.
Custom fields at the group member dimension are not available by default. They can be configured through Chat Console. For details, see Custom Fields.
Response Package Example
{
  "ActionStatus": "OK",
  "ErrorInfo": "",
  "ErrorCode": 0,
  "GroupId": "MyFirstGroup"
}
Response Packet Fields
Field
Type
Description
ActionStatus
String
Request processing result:
OK indicates successful processing.
FAIL: Indicates Failure
ErrorCode
Integer
Error Code:
0: success
Non-zero: failure
ErrorInfo
String
Error message.
GroupId
String
Group ID after successful creation
Error Code Description
Unless a network error (for example, 502 error) occurs, the HTTP return code of this API is 200. The actual error code and error information are indicated by ErrorCode and ErrorInfo in the response packet body.
For common error codes (60000 to 79999), see Error Code document.
The private error codes of this API are as follows:
Error Code
Description of Meaning
10002
Server internal error, please retry.
10003
Illegal Request Command Word
10004
Invalid parameter. Check whether the request is correct according to the error description.
10005
The number of members imported in the request packet exceeds 100. Reduce the number of members imported in the MemberList parameter.
10006
Operation frequency limit. Try to reduce the call frequency. This often occurs when the net group increase in a single day is too large or the operation of obtaining all groups in the App is too frequent.
10007
Insufficient operation permissions. Check the request parameters according to the error information. For example, the specified group type does not allow inviting people to the group, but MemberList is filled in the request packet.
10008
Illegal request. It might be that the signature information carried in the request fails to pass verification. Please try again or submit a ticket to contact technical support.
10016
The App backend has denied this operation through the third-party callback. Please check the returned value of your callback service "Callback before creating a group".
10021
The group ID has been used by others. Please select another group ID.
10025
The group ID has been used by yourself. Please dissolve the group or select another group ID.
10036
The number of created audio-video chat groups exceeds the limit. Please first dissolve part of the audio-video chat groups or refer to Pricing to purchase an upgrade.
10037
The group owner (Owner_Account) specified in the in-progress request has exceeded the limit of the number of groups created and joined. Please ask the group owner to exit part of the groups 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.
10058
The trial version exceeds the limit of 100 groups. You need to purchase a package to increase the group creation limit.
141001
Failed to assign human customer service. No available customer service online.
141002
Internal system error, please retry.
141004
Illegal request parameters, please check and retry.
API Debugging Tools
Debug this interface using the REST API Online Debugging Tool.
References
Dissolve group (v4/group_open_http_svc/destroy_group)
Callbacks That May Be Triggered
Callback before creating a group
Callback after creating a group

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

Parameter	Description
v4/desk_http_svc/create_group	Request API.
sdkappid	Assigned SDKAppID in the Chat console when creating an application.
identifier	Must be an App administrator account. For more details, see App Administrator.
usersig	Generated signature of the App administrator account. For specific operations, see Generate UserSig.
random	Enter a random 32-bit unsigned integer. The value ranges from 0 to 4294967295.
contenttype	The request format has a fixed value of `json`.

Field	Type	Required	Description
Owner_Account	String	Optional.	Group Owner ID (must be an imported account). After filling in, it will be automatically added to the group members; if left empty, the group will have no group owner.
Type	String	Required	GroupType, including Public (stranger social group), Private (i.e., Work, work group).
GroupId	String	Required	To make the group ID simpler and easier to remember and spread, tencent cloud support allows apps to customize group ID when creating a group via REST API.
Name	String	Required	Group name, up to 100 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
Introduction	String	Optional.	Group introduction, up to 400 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
Notification	String	Optional.	Group notice, up to 400 bytes, using UTF-8 encoding, 1 Chinese character equals 3 bytes.
FaceUrl	String	Optional.	Group Avatar URL, up to 500 bytes.
MaxMemberCount	Integer	Optional.	The maximum number of group members. By default, it is the paid package upper limit. For example, it is 20 for the trial version. If you upgrade the package, you need to modify this field by modifying group basic information.
ApplyJoinOption	String	Optional.	Method of handling request to join group. Options include FreeAccess (free joining), NeedPermission (approval required), DisableApply (group join prohibition). If not filled in, the specific default value can be seen in Differences in group joining methods. this field is valid only when creating a group that supports initiation request to join.
InviteJoinOption	String	Optional.	Method for handling invitations to join the group, including FreeAccess (directly invite users to the group without approval and other operations), NeedPermission (requiring approval from the group admin or owner), DisableInvite (unsupported SDK invitation to join the group). This option is not supported by the AVChatRoom group type.
AppDefinedData	Array	Optional.	Custom fields at the group dimension are not available by default. They can be configured through Chat Console. For details, see Custom Fields.
MemberList	Array	Required	Initial group member list, up to 100; for details on member information fields, see group member profile.
AppMemberDefinedData	Array	Optional.	Custom fields at the group member dimension are not available by default. They can be configured through Chat Console. For details, see Custom Fields.

Error Code	Description of Meaning
10002	Server internal error, please retry.
10003	Illegal Request Command Word
10004	Invalid parameter. Check whether the request is correct according to the error description.
10005	The number of members imported in the request packet exceeds 100. Reduce the number of members imported in the `MemberList` parameter.
10006	Operation frequency limit. Try to reduce the call frequency. This often occurs when the net group increase in a single day is too large or the operation of obtaining all groups in the App is too frequent.
10007	Insufficient operation permissions. Check the request parameters according to the error information. For example, the specified group type does not allow inviting people to the group, but `MemberList` is filled in the request packet.
10008	Illegal request. It might be that the signature information carried in the request fails to pass verification. Please try again or submit a ticket to contact technical support.
10016	The App backend has denied this operation through the third-party callback. Please check the returned value of your callback service "Callback before creating a group".
10021	The group ID has been used by others. Please select another group ID.
10025	The group ID has been used by yourself. Please dissolve the group or select another group ID.
10036	The number of created audio-video chat groups exceeds the limit. Please first dissolve part of the audio-video chat groups or refer to Pricing to purchase an upgrade.
10037	The group owner (Owner_Account) specified in the in-progress request has exceeded the limit of the number of groups created and joined. Please ask the group owner to exit part of the groups 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.
10058	The trial version exceeds the limit of 100 groups. You need to purchase a package to increase the group creation limit.
141001	Failed to assign human customer service. No available customer service online.
141002	Internal system error, please retry.
141004	Illegal request parameters, please check and retry.