外观
创建群
以当前用户为群主创建一个群。初始成员来自本人的有效双向好友，群名和头像由服务器生成，之后可以修改。
POST /app/sdk/groups/create
调用方： SDK 客户端 · 认证： IM Token
请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。
请求参数
JSON Body
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
request_id | string | 是 | 本次操作的去重 ID，1–64 位字母、数字、点、下划线、冒号或连字符。同一次操作重试时保持不变。 |
member_ids | string[] | 是 | 1–499 个不重复的成员外部 user_id，每项 1–64 字符，不含控制字符。 不包含自己；目标必须是有效双向好友。 |
请求示例
bash
curl 'https://example.com/app/sdk/groups/create' \
-H "Authorization: Bearer $POPOIM_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"request_id":"outing-20261018-01","member_ids":["linzhou"]}'使用说明
- 只能提交 request_id 和 member_ids，不能在此请求里附带 name。
- 同一创建操作重试保持 request_id 与成员列表一致。
返回参数
成功响应的最外层字段如下。下面所有业务字段都位于 data 中。
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。 |
msg | string | 成功通常为 ok，失败时为错误说明。 |
data | object | 本次请求的业务结果，字段见下表。 |
data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
event_id | string | null | 与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。 |
request_id | string | 本次创建请求的去重 ID。 |
created | boolean | 是否新建群；原请求重试时为 false，并返回同一个群。 |
group | Group | 群资料。 |
membership | Membership | 本人的群状态。 |
permissions | GroupPermissions | 本人当前可执行的群操作。 |
conversation | Conversation | 创建后本人的群会话。 |
返回示例
示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。
展开完整返回示例
json
{
"code": 0,
"msg": "ok",
"data": {
"event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
"request_id": "outing-20261018-01",
"created": true,
"group": {
"group_id": "6284173029",
"owner_id": "chenyue",
"name": "陈悦、林舟",
"avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
"avatar_custom": false,
"announcement": null,
"announcement_author_id": null,
"announcement_author_name": null,
"announcement_updated_at": 0,
"status": "active",
"all_muted": false,
"join_approval_required": false,
"member_count": 2,
"unread_mode": "fanout",
"last_mid": "0",
"last_seq": "0",
"last_message_at": 0,
"conversation_updated_at": 0,
"created_at": 1792301400000,
"updated_at": 1792301400000
},
"conversation": {
"conversation_id": "group_6284173029",
"type": "group",
"target_id": "6284173029",
"name": "陈悦、林舟",
"avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
"member_count": 2,
"group_role": "owner",
"all_muted": false,
"send_forbidden_until": 0,
"last_mid": "0",
"last_seq": "0",
"read_seq": "0",
"peer_read_seq": null,
"announcement_updated_at": 0,
"announcement_unread": false,
"mention_unread": false,
"updated_at": 1792301401000,
"last_message_time": 0,
"last_message": null,
"unread_count": 0,
"pinned": false,
"muted": false,
"state": "hidden",
"peer_presence": null,
"group": {
"group_id": "6284173029",
"owner_id": "chenyue",
"name": "陈悦、林舟",
"avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
"avatar_custom": false,
"announcement": null,
"announcement_author_id": null,
"announcement_author_name": null,
"announcement_updated_at": 0,
"status": "active",
"all_muted": false,
"join_approval_required": false,
"member_count": 2,
"unread_mode": "fanout",
"last_mid": "0",
"last_seq": "0",
"last_message_at": 0,
"conversation_updated_at": 0,
"created_at": 1792301400000,
"updated_at": 1792301400000
}
},
"membership": {
"conversation_id": "group_6284173029",
"status": "active",
"role": "owner",
"remark": "",
"conversation_state": "hidden",
"pinnable": false,
"pinned": false,
"muted": false,
"announcement_unread": false,
"send_forbidden_until": 0,
"joined_at": 1792301400000,
"updated_at": 1792301400000
},
"permissions": {
"send_message": true,
"rename_group": true,
"edit_announcement": true,
"edit_remark": true,
"add_member": true,
"remove_member": true,
"manage_admins": true,
"manage_mute": true,
"manage_join_approval": true,
"share_group": true,
"dissolve_group": true,
"leave_group": false
}
}
}返回对象字段
数组中的每个对象使用同一套字段。点击名称跳到说明：
群资料 · 本人的群成员状态 · 本人的群操作权限 · 会话 · 最后一条消息摘要 · 用户资料 · 在线状态
群资料（Group）
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | string | 公开群 ID，群相关请求使用这个值。 |
owner_id | string | 群主的外部 user_id。 |
name | string | 群名称。 |
avatar | string | 群头像地址。 |
avatar_custom | boolean | 是否由用户上传头像；false 表示服务器生成的组合头像。 |
announcement | string | null | 群公告正文；没有公告时为 null。 |
announcement_author_id | string | null | 最近一次公告发布者的外部 user_id；没有公告时可为 null。 |
announcement_author_name | string | null | 公告发布者的显示名；没有公告时可为 null。 |
announcement_updated_at | integer | 公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。 |
status | string | 群状态：active 正常、disabled 停用、dissolved 已解散。 |
all_muted | boolean | 是否开启全员禁言。 |
join_approval_required | boolean | 扫码加入是否需要群主或管理员审批。 |
member_count | integer | 当前成员人数。 |
unread_mode | string | 未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。 |
last_mid | string | 最新消息 ID；还没有消息时为 "0"。 |
last_seq | string | 最新消息在群内的序号；没有消息时为 "0"。 |
last_message_at | integer | 最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。 |
conversation_updated_at | integer | 群会话内容最后更新时间，Unix 毫秒时间戳。 |
created_at | integer | 建群时间，Unix 毫秒时间戳。 |
updated_at | integer | 群资料最后更新时间，Unix 毫秒时间戳。 |
本人的群成员状态（Membership）
| 字段 | 类型 | 说明 |
|---|---|---|
conversation_id | string | 该群的会话 ID。 |
status | string | active 仍在群中、left 已退出、removed 已被移出、dissolved 群已解散。 |
role | string | owner 群主、admin 管理员、member 普通成员。 |
remark | string | 本人设置的群备注；未设置时为空字符串。 |
conversation_state | string | chatting 显示在会话列表，hidden 隐藏。 |
pinnable | boolean | 当前是否可以置顶；没有消息时通常为 false。 |
pinned | boolean | 本人是否置顶。 |
muted | boolean | 本人是否开启免打扰。 |
announcement_unread | boolean | 本人是否有未读群公告。 |
send_forbidden_until | integer | 本人单独禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。 |
joined_at | integer | 本人入群时间，Unix 毫秒时间戳。 |
updated_at | integer | 本人成员状态最后更新时间，Unix 毫秒时间戳。 |
本人的群操作权限（GroupPermissions）
| 字段 | 类型 | 说明 |
|---|---|---|
send_message | boolean | 本人当前是否可以发送消息。界面可据此显示操作入口，服务器仍会再次检查权限。 |
rename_group | boolean | 本人当前是否可以修改群名。界面可据此显示操作入口，服务器仍会再次检查权限。 |
edit_announcement | boolean | 本人当前是否可以编辑群公告。界面可据此显示操作入口，服务器仍会再次检查权限。 |
edit_remark | boolean | 本人当前是否可以修改个人群备注。界面可据此显示操作入口，服务器仍会再次检查权限。 |
add_member | boolean | 本人当前是否可以添加成员。界面可据此显示操作入口，服务器仍会再次检查权限。 |
remove_member | boolean | 本人当前是否可以移出成员。界面可据此显示操作入口，服务器仍会再次检查权限。 |
manage_admins | boolean | 本人当前是否可以设置或取消管理员。界面可据此显示操作入口，服务器仍会再次检查权限。 |
manage_mute | boolean | 本人当前是否可以设置全员或成员禁言。界面可据此显示操作入口，服务器仍会再次检查权限。 |
manage_join_approval | boolean | 本人当前是否可以修改入群审批设置。界面可据此显示操作入口，服务器仍会再次检查权限。 |
share_group | boolean | 本人当前是否可以分享群二维码。界面可据此显示操作入口，服务器仍会再次检查权限。 |
dissolve_group | boolean | 本人当前是否可以解散群。界面可据此显示操作入口，服务器仍会再次检查权限。 |
leave_group | boolean | 本人当前是否可以退出群。界面可据此显示操作入口，服务器仍会再次检查权限。 |
会话（Conversation）
| 字段 | 类型 | 说明 |
|---|---|---|
conversation_id | string | 会话 ID。读取消息、发送消息和修改会话状态时直接使用此值。 |
type | string | friend 表示单聊，group 表示群聊。 |
target_id | string | 单聊为对方的外部 user_id；群聊为公开 group_id。 |
name | string | 当前账号看到的会话名称，可能已应用个人备注。 |
avatar | string | 会话头像地址。 |
member_count | integer | null | 群成员数；单聊为 null。 |
group_role | string | null | 本人在群中的角色：owner 群主、admin 管理员、member 成员；单聊为 null。 |
all_muted | boolean | 群是否开启全员禁言；单聊为 false。 |
send_forbidden_until | integer | 本人禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。 |
last_mid | string | 最新消息 ID；没有消息时为 "0"。 |
last_seq | string | 最新消息序号；没有消息时为 "0"。 |
read_seq | string | null | 本人已读到的消息序号。未提供个人状态的共享事件可为 null。 |
peer_read_seq | string | null | 单聊对方已读到的序号；群聊为 null。 |
announcement_updated_at | integer | 群公告更新时间；单聊为 0，Unix 毫秒时间戳。 |
announcement_unread | boolean | 本人是否有未读群公告；单聊为 false。 |
mention_unread | boolean | 是否存在尚未读到的群内 @ 提醒；单聊为 false。 |
updated_at | integer | 会话最后更新时间，Unix 毫秒时间戳。 |
last_message_time | integer | 最新消息时间；没有消息时为 0，Unix 毫秒时间戳。 |
last_message | LastMessage | null | 最后一条消息摘要；没有消息时为 null。 |
unread_count | integer | 本人未读消息数，范围 0–100；100 表示至少 100 条。 |
pinned | boolean | 本人是否置顶。 |
muted | boolean | 本人是否开启免打扰。 |
state | string | chatting 表示显示在会话列表，hidden 表示隐藏。 |
peer | User | 仅单聊返回，对方完整资料；群聊不返回此字段。 |
peer_presence | Presence | null | 单聊对方在线状态；群聊或暂时没有状态时为 null。 |
group | Group | 仅群聊返回，完整群资料；单聊不返回此字段。 |
最后一条消息摘要（LastMessage）
| 字段 | 类型 | 说明 |
|---|---|---|
mid | string | 消息 ID。 |
conversation_seq | string | 这条消息在当前会话中的序号。 |
sender_id | string | null | 发送者的外部 user_id；系统消息为 null。 |
sender_name | string | null | 群消息发送者的显示名；单聊中可为 null。 |
type | string | text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。 |
status | string | normal 正常、recalled 已撤回、deleted 已被当前账号删除。 |
text | string | null | 文字或摘要文本；没有文本、已撤回或已删除时为 null。 |
file_name | string | null | 文件名称；非文件消息或内容已清除时为 null。 |
created_at | integer | 发送时间，Unix 毫秒时间戳。 |
updated_at | integer | 消息最后更新时间，Unix 毫秒时间戳。 |
用户资料（User）
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。 |
user_id | string | 宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。 |
username | string | null | 可用于精确搜索的账号；没有设置时为 null。 |
nickname | string | 显示昵称。 |
avatar | string | 头像地址。 |
signature | string | 个性签名；未设置时为空字符串。 |
profile_updated_at | integer | 公开资料最后更新时间，Unix 毫秒时间戳。 |
在线状态（Presence）
| 字段 | 类型 | 说明 |
|---|---|---|
online | boolean | 当前是否在线。 |
online_updated_at | integer | 在线状态最后更新时间，Unix 毫秒时间戳。 |
错误处理
先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。