泡泡 IM

外观

读取好友目录 ​

读取好友及在线状态，支持按首字母分组或按名称、备注筛选。

GET /app/sdk/friends

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

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

请求参数 ​

Query ​

参数类型必填说明
cursorstring否上一次返回的 next_cursor，1–2048 字符；首次读取时不传。游标已包含原筛选条件，不能自行修改或跨账号使用。 与 initial、query 互斥。
initialstring否首字母分组 A–Z 或 #，输入不区分大小写；与 cursor、query 互斥。
querystring否按名称或备注筛选，去除首尾空白后 1–80 字符，不含控制字符；与 cursor 互斥。

请求示例 ​

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

使用说明 ​

  • 首次读取不传参数。继续翻页只传 cursor，不重复提交首字母或关键词。

返回参数 ​

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

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

data 字段 ​

字段类型说明
itemsFriendItem[]本页好友，最多 1000 项。
initialsstring[]当前好友目录中可用的首字母分组。
next_cursorstring | null下一页游标；没有下一页时为 null。
has_moreboolean是否还有下一页。

返回示例 ​

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

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "conversation_id": "friend_bGluemhvdQ",
        "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
        },
        "remark": "林舟 · 行政",
        "blocked": false,
        "display_name": "林舟 · 行政",
        "initial": "L"
      }
    ],
    "initials": [
      "L"
    ],
    "next_cursor": null,
    "has_more": false
  }
}

返回对象字段 ​

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

好友目录项 · 用户资料 · 在线状态

好友目录项（FriendItem） ​

字段类型说明
conversation_idstring与此人的单聊会话 ID。
userUser好友资料。
presencePresence好友在线状态。
remarkstring本人设置的备注；没有备注时为空字符串。
blockedboolean本人是否拉黑对方。
display_namestring目录显示名，优先使用备注。
initialstring当前显示名的首字母分组，A–Z 或 #。

用户资料（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