Create a group

Description

To create a group through this interface.

Upon successful creation of the group, the group owner will receive a notification of successful group creation through the following callback interface in the ZIM SDK, while other group members will receive a notification of joining the group:

iOS	Android	macOS	Windows
groupStateChanged	onGroupStateChanged	groupStateChanged	onGroupStateChanged
Web	Flutter	Unity3D	React Native
groupStateChanged	onGroupStateChanged	OnGroupStateChanged	groupStateChanged

Operation prototype

Request method: POST
Request endpoint: https://zim-api.zego.im/?Action=CreateGroup
Protocol: HTTPS
Rate limit: 20 requests/second

Request parameters

Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Accessing Server APIs - Public parameters.

Parameter	Type	Required	Description
GroupId	String	No	Group ID, the unique identifier of the group, cannot start with #. The maximum length is 32 bytes. If it is empty, it will be created by the ZIM server and defined starting with #.
GroupName	String	No	Group name, the maximum length is 50 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
GroupNotice	String	No	Group announcement, the maximum length is 300 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
GroupAvatar	String	No	Group avatar URL, the maximum length is 500 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
GroupOwner	String	Yes	The user ID of the group owner. The maximum length is 32 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
UserId[]	Array of String	No	The ID of the user who joins the group is required. The maximum length of each user ID is 32 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team. Up to 100 users can be added at one time by default. If you need to adjust it, please contact ZEGOCLOUD technical support team. Note This array does not need to contain group owners. If the group owner is included, the ZIM server will automatically remove duplicates. The group joining time of this array user is equal to the group creation time, that is, CreateGroupTime.
Attributes	Array of Object	No	Group attributes. The upper limit of group attributes is 10. If you need to adjust it, please contact ZEGOCLOUD technical support team.
└Key	String	Yes (only if group properties need to be configured)	The key of the group attribute, the maximum length is 16 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
└Value	String	Yes (only if group properties need to be configured)	The value of the group attribute, the maximum length is 1024 bytes. If you need to adjust it, please contact ZEGOCLOUD technical support team.
CreateGroupTime	Number	No	The timestamp of group creation (millisecond level). If it is 0 or not filled in: the default group is created at the current time. For other values: cannot be greater than the current timestamp.

Note

The GroupId and GroupOwner parameters can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.

Sample request

Request URL:

Untitled

https://zim-api.zego.im/?Action=CreateGroup
&<Common request parameters>

Copied!

Request body:

Untitled

{
    "GroupId": "group",
    "GroupName": "group_name",
    "GroupNotice": "group_notice",
    "GroupAvatar": "https://www.baidu.com/",
    "GroupOwner": "owner",
    "UserId": [
        "user1",
        "user2"
    ],
    "Attributes": [
        {
            "Key": "key1",
            "Value": "value1"
        },
        {
            "Key": "key2",
            "Value": "value2"
        }
    ],
    "CreateGroupTime": 0
}

Copied!

Sample request

Parameter	Type	Description
Code	Number	Return codes.
Message	String	Description of operation results.
RequestId	String	Request ID.
GroupId	String	Group ID.
Members	Array of Object	Information on the successful users who joined the group.
└UserId	String	Group user ID.
└UserName	String	Group user name.
ErrorUsers	Array of Object	Information of users who failed to join the group. Code is 0: ErrorList is empty, and all specified users have successfully joined the group. ErrorList is not empty, it means that some specified users failed to join the group. Please refer to SubCode for processing. Code is not 0: ErrorList is empty, indicating parameter errors, interface frequency limits, and system errors. ErrorList is not empty, indicating all specified users failed to join the group.
└UserId	String	Failed user ID.
└SubCode	Number	The specific return code for user failure to join the group.

Sample response

Untitled

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

Copied!

Return codes

The following table describes only the return codes related to the business logic of the operation. For the complete list of return codes, see Return codes.

Return Code	Description	Solution
660000002	Error in parameter.	Please check the request parameters.
660600010	Exceeded the call frequency limit.	Please try again later.
660600011	The group already exists.	Please use other GroupId.
660600012	The number of groups exceeds the limit.	Please upgrade your package.
660600013	The group owner does not exist.	Please check whether the user ID of the group owner is correct.
660600014	An error occurred when modifying the group owner's group list.	Please contact ZEGOCLOUD technical support team.
660600015	An error occurred when the ZIM server performed the db operation.	Please contact ZEGOCLOUD technical support team.
660600016	The number of group members exceeds the limit.	Please reduce the number of group members.
660600017	The user failed to join the group when creating the group.	Please contact ZEGOCLOUD technical support team.
660600019	The number of attributes exceeds the limit.	Please reduce the number of group attributes to a maximum of 10 by default.
660600020	The property's Key or Value length is wrong.	Please check the length of relevant parameters.