CreateGroup

POST

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

通过此接口创建群组。

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

iOS	Android	macOS	Windows
groupStateChanged	onGroupStateChanged	groupStateChanged	onGroupStateChanged

Web	小程序	Flutter	React Native
groupStateChanged	groupStateChanged	onGroupStateChanged	groupStateChanged

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

说明

参数 GroupOwner 和 UserId 对应的用户已在客户端调用 login 方法登录 ZIM 服务，或开发者已调用服务端 API 注册相关的 userID。

说明

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

说明

调用频率限制：20 次/秒。

Request

Query Parameters

Action string必填

可选值: [CreateGroup]

接口原型参数

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

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

application/json

Body

required

GroupId string

可选值: <= 32 characters

群 ID，群的唯一标识，不能以 “#” 开头。长度上限为 32 字节。为空则由 ZIM 服务端创建，并以 “#“ 开头定义。

GroupName string

可选值: <= 50 characters

群名称，长度上限为 50 字节。如需调整，请联系 ZEGO 技术支持。

GroupNotice string

可选值: <= 300 characters

群公告，长度上限为 300 字节。如需调整，请联系 ZEGO 技术支持。

GroupAvatar string

可选值: <= 500 characters

群头像 URL，长度上限为 500 字节。如需调整，请联系 ZEGO 技术支持。

GroupOwner string必填

可选值: <= 32 characters

群主的用户 ID。长度上限为 32 字节。如需调整，请联系 ZEGO 技术支持。

UserId string[]

可选值: <= 100

需要入群用户的 ID。每个用户 ID 的长度上限为 32 字节。如需调整，请联系 ZEGO 技术支持。

说明

此数组无需包含群主。如果包含了群主，ZIM 服务端会自动去重。

此数组用户的入群时间等于群组创建时间，即 CreateGroupTime。

Attributes object[]

群属性。群属性上限为 10 个。如需调整，请联系 ZEGO 技术支持。

Array[

Key string必填

群属性的键，长度上限为 16 个字节。如需调整，请联系 ZEGO 技术支持。

Value string必填

群属性的值，长度上限为 1024 个字节。如需调整，请联系 ZEGO 技术支持。

]

CreateGroupTime number

创建群的时间戳（毫秒级别）。

为 0 或者不填：默认群组为当前时间创建。
为其他值：不可大于当前时间戳。

Responses

application/json

数据结构
按数据结构生成的示例
示例

Schema

Code number

返回码。

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

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

Message string

操作结果描述。

RequestId string

请求 ID。

GroupId string

群 ID。

Members object[]

入群成功用户信息。

Array[

UserId string

群用户 ID。

UserName string

群用户名称。

]

ErrorUsers object[]

入群失败用户信息。

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

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

Array[

UserId string

失败用户 ID。

SubCode number

用户入群失败的具体返回码，完整返回码请参考 Code 说明或者全局返回码。

]

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