读取群目录

读取当前账号加入的群，或者按群名、个人备注筛选。

GET /app/sdk/groups

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

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

请求参数

Query

参数	类型	必填	说明
cursor	string	否	上一次返回的 next_cursor，1–2048 字符；首次读取时不传。游标已包含原筛选条件，不能自行修改或跨账号使用。
query	string	否	按名称或备注筛选，去除首尾空白后 1–80 字符，不含控制字符；与 cursor 互斥。

请求示例

curl 'https://example.com/app/sdk/groups' \
  -H "Authorization: Bearer $POPOIM_TOKEN"

使用说明

• cursor 和 query 不能同时提交。继续搜索结果的下一页时，只传 next_cursor。

返回参数

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

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

data 字段

字段	类型	说明
items	GroupDirectoryItem[]	本页群目录，最多 50 项。
next_cursor	string | null	下一页游标；没有下一页时为 null。
has_more	boolean	是否还有下一页。

返回示例

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "conversation_id": "group_6284173029",
        "group_id": "6284173029",
        "name": "秋日海岸出游",
        "avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
        "member_count": 2,
        "remark": "",
        "display_name": "秋日海岸出游",
        "role": "owner",
        "all_muted": false,
        "send_forbidden_until": 0,
        "joined_at": 1792301400000,
        "updated_at": 1792301400000
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

返回对象字段

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

群目录项

群目录项（GroupDirectoryItem）

字段	类型	说明
conversation_id	string	群会话 ID。
group_id	string	公开群 ID。
name	string	群名称。
avatar	string	群头像地址。
member_count	integer	成员人数。
remark	string	本人设置的群备注；没有备注时为空字符串。
display_name	string	本人看到的群显示名，优先使用备注。
role	string	owner 群主、admin 管理员、member 成员。
all_muted	boolean	是否全员禁言。
send_forbidden_until	integer	本人的单独禁言到期时间，Unix 毫秒；0 表示未单独禁言。
joined_at	integer	本人入群时间，Unix 毫秒。
updated_at	integer	目录项更新时间，Unix 毫秒。

错误处理

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

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