CreateGroup

POST

https://zim-api.zego.im/

By calling this API, you can create a group.

After successful group creation, through the following ZIM SDK callback interfaces, the group owner will receive a notification of successful group creation, and other group members will receive a notification of joining the group:

iOS	Android	macOS	Windows
groupStateChanged	onGroupStateChanged	groupStateChanged	onGroupStateChanged

Web	Mini Program	Flutter	React Native
groupStateChanged	groupStateChanged	onGroupStateChanged	groupStateChanged

Unity3D	uni-app \| uni-app x	HarmonyOS
OnGroupStateChanged	groupStateChanged	groupStateChanged

Note

The users corresponding to the parameters GroupOwner and UserId have logged in to the ZIM service by calling the login method on the client, or the developer has registered the relevant userID by calling the server-side API.

Note

The parameters GroupId and GroupOwner only support numbers, English characters, and '!','#','$','%','&','(',')','+','\'',':',';','<','=','.','>','?','@', '[',']','^','_','{','}','|','~'.

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [CreateGroup]

API prototype parameter

https://zim-api.zego.im/?Action=CreateGroup

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

Timestamp int64required

💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

Signature stringrequired

💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

application/json

Body

required

GroupId string

Possible values: <= 32 characters

Group ID, the unique identifier of the group, cannot start with "#". The maximum length is 32 bytes. If empty, it will be created by the ZIM server and defined with a "#" prefix.

GroupName string

Possible values: <= 50 characters

Group name. The maximum length is 50 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

GroupNotice string

Possible values: <= 300 characters

Group notice. The maximum length is 300 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

GroupAvatar string

Possible values: <= 500 characters

Group avatar URL. The maximum length is 500 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

GroupOwner stringrequired

Possible values: <= 32 characters

User ID of the group owner. The maximum length is 32 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

UserId string[]

Possible values: <= 100

IDs of users who need to join the group. The maximum length of each user ID is 32 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

Note

This array does not need to include the group owner. If the group owner is included, the ZIM server will automatically deduplicate.

The join time of users in this array equals the group creation time, i.e., CreateGroupTime.

Attributes object[]

Group attributes. The maximum number of group attributes is 10. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

Array[

Key stringrequired

Key of the group attribute. The maximum length is 16 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

Value stringrequired

Value of the group attribute. The maximum length is 1024 bytes. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

]

CreateGroupTime number

Timestamp for creating the group (in milliseconds).

If 0 or not filled: The group is created at the current time by default.
If other value: Cannot be greater than the current timestamp.

Responses

application/json

Schema
Example (from schema)
Example

Schema

Code number

Return code.

The following only lists the Code and SubCode related to the API business logic. For the complete return codes, please refer to Return codes.

Code / SubCode	Description	Suggested Solution
660000002	Parameter error.	Please check the request parameters.
660600010	API call frequency limit exceeded.	Please try again later.
660600011	Group already exists.	Please use another GroupId.
660600012	Number of groups exceeds the limit.	Please upgrade your plan.
660600013	Group owner does not exist.	Please check if the group owner ID is correct.
660600014	Error modifying the group owner's group list.	Please contact ZEGOCLOUD Technical Support.
660600015	ZIM server encountered an error executing db operation.	Please contact ZEGOCLOUD Technical Support.
660600016	Number of group members exceeds the limit.	Please reduce the number of group members.
660600017	User failed to join the group during group creation.	Please contact ZEGOCLOUD Technical Support.
660600019	Number of attributes exceeds the limit.	Maximum of 10 by default.
660600020	Attribute Key or Value length error.	Please check the length.

Message string

Description of the operation result.

RequestId string

Request ID.

GroupId string

Group ID.

Members object[]

Information of users who successfully joined the group.

Array[

UserId string

Group user ID.

UserName string

Group user name.

]

ErrorUsers object[]

Information of users who failed to join the group.

When Code is 0:
If ErrorList is empty, all specified users successfully joined the group.
If ErrorList is not empty, it means some specified users failed to join the group. Please refer to SubCode for handling.

When Code is not 0:
If ErrorList is empty, it indicates parameter error, API frequency limit, or system error.
If ErrorList is not empty, it means all specified users failed to join the group.

Array[

UserId string

Failed user ID.

SubCode number

Specific return code for user's failure to join the group. For the complete return codes, please refer to the Code description or Return codes.

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "GroupId": "string",
  "Members": [
    {
      "UserId": "owner",
      "UserName": "owner"
    }
  ],
  "ErrorUsers": [
    {
      "UserId": "user2",
      "SubCode": 660000015
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "GroupId": "string",
  "Members": [
    {
      "UserId": "owner",
      "UserName": "owner"
    }
  ],
  "ErrorUsers": [
    {
      "UserId": "user2",
      "SubCode": 660000015
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "GroupId": "group",
  "Members": [
    {
      "UserId": "owner",
      "UserName": "owner"
    },
    {
      "UserId": "user1",
      "UserName": "user1"
    }
  ],
  "ErrorUsers": [
    {
      "UserId": "user2",
      "SubCode": 660000015
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "GroupId": "group",
  "Members": [
    {
      "UserId": "owner",
      "UserName": "owner"
    },
    {
      "UserId": "user1",
      "UserName": "user1"
    }
  ],
  "ErrorUsers": [
    {
      "UserId": "user2",
      "SubCode": 660000015
    }
  ]
}

CreateGroup

https://zim-api.zego.im/

Request

Query Parameters

Body

Responses​

Responses