泡泡 IM

外观

按账号精确查找用户 ​

根据完整账号查找用户，常用于添加好友。这里是精确匹配；搜索聊天记录或名称请使用搜索接口。

GET /app/sdk/users/search

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

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

请求参数 ​

Query ​

参数类型必填说明
usernamestring是需要精确匹配的账号，1–64 字符，不含控制字符。

请求示例 ​

bash
curl -G 'https://example.com/app/sdk/users/search' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  --data-urlencode 'username=linzhou'

使用说明 ​

  • 接口有请求频率限制，不适合每次输入一个字就调用。用户提交完整账号后再请求。

返回参数 ​

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

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

data 字段 ​

字段类型说明
itemsUserSearchItem[]匹配结果，空数组表示未找到，找到时最多一项。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "ip_region": null,
        "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
        },
        "relation": {
          "status": "friend",
          "blocked": false,
          "remark": "",
          "display_name": "林舟",
          "initial": "L",
          "updated_at": 1792301400000
        },
        "conversation_settings": {
          "available": true,
          "pinnable": true,
          "pinned": false,
          "muted": false
        },
        "permissions": {
          "message": true,
          "set_remark": true,
          "add_friend": false,
          "block_user": true,
          "report_user": true
        },
        "request": null
      }
    ]
  }
}

返回对象字段 ​

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

账号搜索结果 · 用户资料 · 在线状态 · 与当前用户的关系 · 个人会话设置 · 用户资料页操作权限 · 申请或邀请 · 群资料 · 申请处理权限

账号搜索结果（UserSearchItem） ​

字段类型说明
ip_regionstring | nullIP 属地展示文字；没有信息时为 null。
conversation_idstring与此人的单聊会话 ID。
userUser目标用户资料。
presencePresence目标用户在线状态。
relationRelation本人和目标用户的好友关系。
conversation_settingsConversationSettings本人对此会话的设置。
permissionsProfilePermissions当前可执行的操作。
requestNotice | null与此用户已有的好友申请；没有时为 null。

用户资料（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 毫秒时间戳。

与当前用户的关系（Relation） ​

字段类型说明
statusstringfriend 表示好友；stranger 表示非好友。
blockedboolean本人是否已拉黑对方。
remarkstring本人对好友的备注；没有备注时为空字符串。
display_namestring当前账号应显示的名称，优先使用备注。
initialstring显示名首字母分组：A–Z 或 #。
updated_atinteger关系最后更新时间；没有关系记录时为 0，Unix 毫秒时间戳。

个人会话设置（ConversationSettings） ​

字段类型说明
availableboolean是否已存在可设置的会话记录。
pinnableboolean当前是否可以置顶。
pinnedboolean本人是否已置顶。
mutedboolean本人是否已开启免打扰。

用户资料页操作权限（ProfilePermissions） ​

字段类型说明
messageboolean当前是否允许发送消息。
set_remarkboolean当前是否允许设置备注。
add_friendboolean当前是否允许发送好友申请。
block_userboolean当前是否允许设置拉黑状态。
report_userboolean当前是否允许举报此用户。

申请或邀请（Notice） ​

字段类型说明
notice_idstring申请 ID；读取时为十进制字符串，提交处理请求时使用正整数。
typestringfriend_request 好友申请、group_join_request 入群申请、group_invitation 群邀请。
directionstringreceived 表示收到的申请，sent 表示本人发出的申请。
statusstringpending 待处理、accepted 已同意、rejected 已拒绝、expired 已过期、revoked 已撤销。
messagestring申请说明；可能为空字符串。
sourcestring申请来源，例如 search、profile、qr；由具体业务产生。
created_atinteger申请创建时间，Unix 毫秒时间戳。
updated_atinteger申请最后更新时间，Unix 毫秒时间戳。
handled_atinteger | null申请处理时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
actorUser发起人资料。
recipientUser接收人资料。
subjectUser | null群邀请中被邀请人的资料；其他申请通常为 null。
groupGroup | null关联群资料；好友申请为 null。
permissionsNoticePermissions当前账号能否同意或拒绝。

群资料（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 毫秒时间戳。

申请处理权限（NoticePermissions） ​

字段类型说明
acceptboolean当前账号是否可以同意此申请。
rejectboolean当前账号是否可以拒绝此申请。

错误处理 ​

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

返回用户、好友与申请接口列表 · HTTP 请求约定

Copyright © 泡泡 IM