OpenIM文档

输入至少两个字符来搜索标题和路径。

简中

语言

ENEnglishEnglish docs简中简体中文中文文档
浏览 平台 API
服务端 API

创建群组

复制

使用 创建群组 从可信后端调用 OpenIM 群组 REST 接口。创建一个 OpenIM 群组，并设置群主、初始成员、管理员和群资料。 请先在接入准备中配置 API 地址和管理员 Token；接口参数通过请求头和 JSON 请求体传递。

HTTP 请求

POST {API_ADDRESS}/group/create_group

请求示例

curl --request POST "${API_ADDRESS}/group/create_group" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "memberUserIDs": [
    "user_001",
    "user_002"
  ],
  "adminUserIDs": [
    "user_admin"
  ],
  "ownerUserID": "user_owner",
  "groupInfo": {
    "groupID": "group_001",
    "groupName": "产品交流群",
    "notification": "欢迎使用 OpenIM",
    "introduction": "用于产品交流的群组",
    "faceURL": "https://example.com/group.png",
    "ex": "",
    "groupType": 2,
    "needVerification": 0,
    "lookMemberInfo": 0,
    "applyMemberFriend": 0
  },
  "sendMessage": true
}'
安全提示：管理员 Token 只能保存在可信后端服务中，不能下发到客户端或写入前端代码。客户端登录应使用服务端签发的用户 Token。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递业务参数。

请求头

Header是否必填类型说明
operationID是string每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token是stringAPP 管理员 Token；仅保存在可信后端服务中。
Content-Type: application/json是string请求体为 JSON 时必须设置。

请求体

{
  "memberUserIDs": [
    "user_001",
    "user_002"
  ],
  "adminUserIDs": [
    "user_admin"
  ],
  "ownerUserID": "user_owner",
  "groupInfo": {
    "groupID": "group_001",
    "groupName": "产品交流群",
    "notification": "欢迎使用 OpenIM",
    "introduction": "用于产品交流的群组",
    "faceURL": "https://example.com/group.png",
    "ex": "",
    "groupType": 2,
    "needVerification": 0,
    "lookMemberInfo": 0,
    "applyMemberFriend": 0
  },
  "sendMessage": true
}
参数名是否必填类型说明
memberUserIDs否array初始普通成员用户 ID 列表，最多 1000 个。
adminUserIDs否array初始管理员用户 ID 列表。
ownerUserID是string群主用户 ID。
groupInfo是object群资料对象，结构为群组模块的 GroupInfo。
groupInfo.groupID否string群 ID；不传时由服务端生成。
groupInfo.groupName是string群名称。
groupInfo.notification否string群公告。
groupInfo.introduction否string群介绍。
groupInfo.faceURL否string群头像 URL。
groupInfo.ex否string群扩展字段。
groupInfo.groupType是int群类型，参见群组模块的 GroupType；当前接口固定传 2。
groupInfo.needVerification否int入群验证策略，参见群组模块的 GroupVerification。
groupInfo.lookMemberInfo否int是否允许查看群成员资料。
groupInfo.applyMemberFriend否int是否允许从群成员处添加好友。
sendMessage否boolean是否发送群创建通知。
displayIsRead 商业版否boolean是否展示群消息已读状态；服务端可能根据群规模自动关闭该能力。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "groupInfo": {
      "groupID": "group_001",
      "groupName": "产品交流群",
      "notification": "欢迎使用 OpenIM",
      "introduction": "用于产品交流的群组",
      "faceURL": "https://example.com/group.png",
      "ownerUserID": "user_owner",
      "createTime": 1719800000000,
      "memberCount": 3,
      "ex": "",
      "status": 0,
      "creatorUserID": "user_owner",
      "groupType": 2,
      "needVerification": 0,
      "lookMemberInfo": 0,
      "applyMemberFriend": 0,
      "notificationUpdateTime": 0,
      "notificationUserID": ""
    }
  }
}

响应参数

参数名类型说明
errCodeint业务错误码，0 表示成功。
errMsgstring错误简要信息，成功时通常为空。
errDltstring错误详细信息，成功时通常为空。
dataobject接口返回数据。
data.groupInfoobject创建后的群资料，结构为群组模块的 GroupInfo。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}
错误场景可能原因处理方式
鉴权失败token 缺失、过期，或不是可调用管理端接口的管理员 Token。重新获取 APP 管理员 Token，并只在可信后端保存。
链路追踪困难operationID 缺失或在大量请求中重复使用。为每次请求生成独立 operationID，并在服务端日志中保留。
参数校验失败请求体字段类型、必填字段或枚举值不符合接口要求。对照请求体参数表和限制说明检查字段。

权限和限制

  • 创建群组、写入群主和初始成员关系，并可能向相关用户下发群创建通知。
  • groupInfo 和 ownerUserID 必填。
  • groupInfo.groupType 只能传 2。
  • memberUserIDs 最多 1000 个。
  • 所有数组型请求参数建议控制在 1000 个元素以内。

相关页面