泡泡 IM

外观

修改个人群备注 ​

设置仅当前账号可见的群备注。

POST /app/sdk/groups/remark

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数 ​

JSON Body ​

参数类型必填说明
group_idstring是公开群 ID，1–32 位字母、数字、点、下划线或连字符。
remarkstring是最多 80 字符，不含控制字符；空字符串清空备注。

请求示例 ​

bash
curl 'https://example.com/app/sdk/groups/remark' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"group_id":"6284173029","remark":"行政部 · 秋日出游"}'

使用说明 ​

  • 需具备 permissions.edit_remark 权限。以群详情当前返回的权限为准。
  • 只提交上表字段；回包会返回最新群资料、本人状态和权限，可直接更新当前页面。

返回参数 ​

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段类型说明
codeinteger0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msgstring成功通常为 ok，失败时为错误说明。
dataobject本次请求的业务结果，字段见下表。

data 字段 ​

字段类型说明
event_idstring | null与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。
changedboolean本次操作是否实际改变了服务器数据；设置值原本相同时为 false。
groupGroup群资料。
membershipMembership本人的群状态。
permissionsGroupPermissions本人当前可执行的群操作。
members_previewMembersPreview最多 15 位群成员的预览。

返回示例 ​

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "group": {
      "group_id": "6284173029",
      "owner_id": "chenyue",
      "name": "秋日海岸出游",
      "avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
      "avatar_custom": false,
      "announcement": "周六 8:30 公司楼下集合，请带好防晒用品。",
      "announcement_author_id": "chenyue",
      "announcement_author_name": "陈悦",
      "announcement_updated_at": 1792301400000,
      "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": 1792301400000,
      "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
    },
    "members_preview": {
      "items": [
        {
          "user": {
            "id": "1024",
            "user_id": "chenyue",
            "username": "chenyue",
            "nickname": "陈悦",
            "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
            "signature": "一起发现沿途的风景",
            "profile_updated_at": 1792301400000
          },
          "presence": {
            "online": true,
            "online_updated_at": 1792301400000
          },
          "display_name": "陈悦",
          "role": "owner",
          "send_forbidden_until": 0,
          "joined_at": 1792301400000,
          "updated_at": 1792301400000
        },
        {
          "user": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "presence": {
            "online": true,
            "online_updated_at": 1792301400000
          },
          "display_name": "林舟",
          "role": "member",
          "send_forbidden_until": 0,
          "joined_at": 1792301400000,
          "updated_at": 1792301400000
        }
      ],
      "has_more": false
    },
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
    "changed": true
  }
}

返回对象字段 ​

数组中的每个对象使用同一套字段。点击名称跳到说明：

群资料 · 本人的群成员状态 · 本人的群操作权限 · 群成员预览 · 群成员 · 用户资料 · 在线状态

群资料（Group） ​

字段类型说明
group_idstring公开群 ID，群相关请求使用这个值。
owner_idstring群主的外部 user_id。
namestring群名称。
avatarstring群头像地址。
avatar_customboolean是否由用户上传头像；false 表示服务器生成的组合头像。
announcementstring | null群公告正文；没有公告时为 null。
announcement_author_idstring | null最近一次公告发布者的外部 user_id；没有公告时可为 null。
announcement_author_namestring | null公告发布者的显示名；没有公告时可为 null。
announcement_updated_atinteger公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
statusstring群状态：active 正常、disabled 停用、dissolved 已解散。
all_mutedboolean是否开启全员禁言。
join_approval_requiredboolean扫码加入是否需要群主或管理员审批。
member_countinteger当前成员人数。
unread_modestring未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
last_midstring最新消息 ID；还没有消息时为 "0"。
last_seqstring最新消息在群内的序号；没有消息时为 "0"。
last_message_atinteger最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
conversation_updated_atinteger群会话内容最后更新时间，Unix 毫秒时间戳。
created_atinteger建群时间，Unix 毫秒时间戳。
updated_atinteger群资料最后更新时间，Unix 毫秒时间戳。

本人的群成员状态（Membership） ​

字段类型说明
conversation_idstring该群的会话 ID。
statusstringactive 仍在群中、left 已退出、removed 已被移出、dissolved 群已解散。
rolestringowner 群主、admin 管理员、member 普通成员。
remarkstring本人设置的群备注；未设置时为空字符串。
conversation_statestringchatting 显示在会话列表，hidden 隐藏。
pinnableboolean当前是否可以置顶；没有消息时通常为 false。
pinnedboolean本人是否置顶。
mutedboolean本人是否开启免打扰。
announcement_unreadboolean本人是否有未读群公告。
send_forbidden_untilinteger本人单独禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。
joined_atinteger本人入群时间，Unix 毫秒时间戳。
updated_atinteger本人成员状态最后更新时间，Unix 毫秒时间戳。

本人的群操作权限（GroupPermissions） ​

字段类型说明
send_messageboolean本人当前是否可以发送消息。界面可据此显示操作入口，服务器仍会再次检查权限。
rename_groupboolean本人当前是否可以修改群名。界面可据此显示操作入口，服务器仍会再次检查权限。
edit_announcementboolean本人当前是否可以编辑群公告。界面可据此显示操作入口，服务器仍会再次检查权限。
edit_remarkboolean本人当前是否可以修改个人群备注。界面可据此显示操作入口，服务器仍会再次检查权限。
add_memberboolean本人当前是否可以添加成员。界面可据此显示操作入口，服务器仍会再次检查权限。
remove_memberboolean本人当前是否可以移出成员。界面可据此显示操作入口，服务器仍会再次检查权限。
manage_adminsboolean本人当前是否可以设置或取消管理员。界面可据此显示操作入口，服务器仍会再次检查权限。
manage_muteboolean本人当前是否可以设置全员或成员禁言。界面可据此显示操作入口，服务器仍会再次检查权限。
manage_join_approvalboolean本人当前是否可以修改入群审批设置。界面可据此显示操作入口，服务器仍会再次检查权限。
share_groupboolean本人当前是否可以分享群二维码。界面可据此显示操作入口，服务器仍会再次检查权限。
dissolve_groupboolean本人当前是否可以解散群。界面可据此显示操作入口，服务器仍会再次检查权限。
leave_groupboolean本人当前是否可以退出群。界面可据此显示操作入口，服务器仍会再次检查权限。

群成员预览（MembersPreview） ​

字段类型说明
itemsGroupMember[]最多 15 位成员；完整列表使用群成员接口。
has_moreboolean是否还有未包含在预览中的成员。

群成员（GroupMember） ​

字段类型说明
userUser成员资料。
presencePresence | null成员在线状态；没有状态时为 null。
display_namestring成员显示名。
rolestringowner 群主、admin 管理员、member 普通成员。
send_forbidden_untilinteger单独禁言到期时间；0 表示未单独禁言，Unix 毫秒时间戳。
joined_atinteger入群时间，Unix 毫秒时间戳。
updated_atinteger成员资料或成员状态的最后更新时间，Unix 毫秒时间戳。

用户资料（User） ​

字段类型说明
idstringIM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
user_idstring宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
usernamestring | null可用于精确搜索的账号；没有设置时为 null。
nicknamestring显示昵称。
avatarstring头像地址。
signaturestring个性签名；未设置时为空字符串。
profile_updated_atinteger公开资料最后更新时间，Unix 毫秒时间戳。

在线状态（Presence） ​

字段类型说明
onlineboolean当前是否在线。
online_updated_atinteger在线状态最后更新时间，Unix 毫秒时间戳。

错误处理 ​

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回群与成员接口列表 · HTTP 请求约定

Copyright © 泡泡 IM