logo
当前页

创建群组


描述

通过此接口创建群组。

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

iOSAndroidmacOSWindows
groupStateChangedonGroupStateChangedgroupStateChangedonGroupStateChanged
Web小程序FlutterUnity3D
groupStateChangedgroupStateChangedonGroupStateChangedOnGroupStateChanged
uni-appReact NativeHarmonyOS
groupStateChangedgroupStateChangedgroupStateChanged

接口原型

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

请求参数

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

说明

以下 GroupOwnerUserId 对应的用户已在客户端调用 login 方法登录 ZIM 服务,或开发者已调用 服务端 API 注册相关的 userID。

参数类型是否必选描述
GroupIdString群 ID,群的唯一标识,不能以 # 开头。长度上限为 32 字节。为空则由 ZIM 服务端创建,并以 # 开头定义。
GroupNameString群名称,长度上限为 50 字节。如需调整,请联系 ZEGO 技术支持。
GroupNoticeString群公告,长度上限为 300 字节。如需调整,请联系 ZEGO 技术支持。
GroupAvatarString群头像 URL,长度上限为 500 字节。如需调整,请联系 ZEGO 技术支持。
GroupOwnerString群主的用户 ID。长度上限为 32 字节。如需调整,请联系 ZEGO 技术支持。
UserIdArray of String需要入群用户的 ID。每个用户 ID 的长度上限为 32 字节。如需调整,请联系 ZEGO 技术支持。
默认支持一次性最多添加 100 名用户。如需调整,请联系 ZEGO 技术支持。
说明
  • 此数组无需包含群主。如果包含了群主,ZIM 服务端会自动去重。
  • 此数组用户的入群时间等于群组创建时间,即 CreateGroupTime。
AttributesArray of Object群属性。群属性上限为 10 个。如需调整,请联系 ZEGO 技术支持。
└KeyString是(仅当需要配置群属性时)群属性的键,长度上限为 16 个字节。如需调整,请联系 ZEGO 技术支持。
└ValueString是(仅当需要配置群属性时)群属性的值,长度上限为 1024 个字节。如需调整,请联系 ZEGO 技术支持。
CreateGroupTimeNumber创建群的时间戳(毫秒级别)。
  • 为 0 或者不填:默认群组为当前时间创建。
  • 为其他值:不可大于当前时间戳。
说明

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

请求示例

  • 请求地址 URL:
Untitled
https://zim-api.zego.im/?Action=CreateGroup
&<公共请求参数>
1
Copied!
  • 请求消息体:
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
}
1
Copied!

响应参数

参数类型描述
CodeNumber返回码。
MessageString操作结果描述。
RequestIdString请求 ID。
GroupIdString群 ID。
MembersArray of Object入群成功用户信息。
└UserIdString群用户 ID。
└UserNameString群用户名称。
ErrorUsersArray of Object

入群失败用户信息。

  • Code 为 0:

    • ErrorList 为空,全部指定用户入群成功。
    • ErrorList 不为空,表示部分指定用户入群失败,请参考 SubCode 处理。

  • Code 不为 0:

    • ErrorList 为空,表示参数错误、接口频率限制、系统错误。
    • ErrorList 不为空,表示全部指定用户入群失败。

└UserIdString失败用户 ID。
└SubCodeNumber用户入群失败的具体返回码。

响应示例

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

返回码

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

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

Previous

查询用户是否在房间内

Next

修改群组规格限制