文档中心
即时通讯
服务端 API
群组相关
创建群组

创建群组

更新时间：2024-05-27 10:22

描述

通过此接口创建群组。

创建群组成功，通过以下 ZIM SDK 的回调接口，群主会收到群组创建成功的通知，其他群成员会收到加入群组的通知：

iOS	Android	macOS	Windows	Web
groupStateChanged	onGroupStateChanged	groupStateChanged	onGroupStateChanged	groupStateChanged
小程序	Flutter	Unity3D	uni-app	React Native
groupStateChanged	onGroupStateChanged	OnGroupStateChanged	groupStateChanged	groupStateChanged

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=CreateGroup
传输协议：HTTPS
调用频率限制：20 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
GroupId	String	否	群 ID，群的唯一标识，不能以 # 开头。长度上限为 32 字节。为空则由 ZIM 服务端创建，并以 # 开头定义。
GroupName	String	否	群名称，长度上限为 50 字节。如需调整，请联系 ZEGO 技术支持。
GroupNotice	String	否	群公告，长度上限为 300 字节。如需调整，请联系 ZEGO 技术支持。
GroupAvatar	String	否	群头像 URL，长度上限为 500 字节。如需调整，请联系 ZEGO 技术支持。
GroupOwner	String	是	群主的用户 ID。长度上限为 32 字节。如需调整，请联系 ZEGO 技术支持。
UserId[]	Array of String	否	需要入群用户的 ID。每个用户 ID 的长度上限为 32 字节。如需调整，请联系 ZEGO 技术支持。默认支持一次性最多添加 100 名用户。如需调整，请联系 ZEGO 技术支持。此数组无需包含群主。如果包含了群主，ZIM 服务端会自动去重。此数组用户的入群时间等于群组创建时间，即 CreateGroupTime。
Attributes	Array of Object	否	群属性。群属性上限为 10 个。如需调整，请联系 ZEGO 技术支持。
Key	String	是（仅当需要配置群属性时）	群属性的键，长度上限为 16 个字节。如需调整，请联系 ZEGO 技术支持。
Value	String	是（仅当需要配置群属性时）	群属性的值，长度上限为 1024 个字节。如需调整，请联系 ZEGO 技术支持。
CreateGroupTime	Number	否	创建群的时间戳（毫秒级别）。为 0 或者不填：默认群组为当前时间创建。为其他值：不可大于当前时间戳。

GroupId 和 GroupOwner 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，''，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=CreateGroup
&<公共请求参数>

请求消息体：

{
    "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
}

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。
GroupId	String	群 ID。
Members	Array of Object	入群成功用户信息。
UserId	String	群用户 ID。
UserName	String	群用户名称。
ErrorUsers	Array of Object	入群失败用户信息。 Code 为 0： ErrorList 为空，全部指定用户入群成功。 ErrorList 不为空，表示部分指定用户入群失败，请参考 SubCode 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示全部指定用户入群失败。
UserId	String	失败用户 ID。
SubCode	Number	用户入群失败的具体返回码。

响应示例

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

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000002	参数错误。	请检查请求参数。
660600010	超出调用频率限制。	请稍后再试。
660600011	群已经存在。	请使用其他 GroupId。
660600012	群数量超过限制。	请升级套餐。
660600013	群主不存在。	请检查群主的用户 ID 是否正确。
660600014	修改群主的群列表出错。	请联系 ZEGO 技术支持。
660600015	ZIM 服务端执行 db 操作出错。	请联系 ZEGO 技术支持。
660600016	群成员数量超过限制。	请减少群成员数量。
660600017	创建群时用户进群失败。	请联系 ZEGO 技术支持。
660600019	属性数量超过限制。	请减少群属性，默认最多 10 个。
660600020	属性的 Key 或 Value 长度错误。	请检查相关参数的长度。