统一搜索

一次查询返回会话、好友、群和消息四组结果，适合应用内的全局搜索。

GET /app/sdk/search

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

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

请求参数

Query

参数	类型	必填	说明
query	string	是	搜索关键词，1–80 字符，不含控制字符。

请求示例

curl -G 'https://example.com/app/sdk/search' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  --data-urlencode 'query=海岸'

使用说明

• 同一对象已经进入 conversations 分组时，不会再重复放入 friends 或 groups。
• 每组最多 20 项。消息组按会话汇总，每个会话先给出一条命中的消息。需要在某个会话中继续查找时，使用搜索会话消息。

返回参数

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

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

data 字段

字段	类型	说明
query	string	本次搜索关键词。
conversations	SearchSection	已存在的会话命中结果。
friends	SearchSection	没有放入会话分组的好友结果。
groups	SearchSection	没有放入会话分组的群结果。
messages	MessageSearchSection	聊天记录命中结果。

返回示例

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "query": "海岸",
    "conversations": {
      "items": [],
      "limited": false
    },
    "friends": {
      "items": [],
      "limited": false
    },
    "groups": {
      "items": [],
      "limited": false
    },
    "messages": {
      "items": [
        {
          "conversation_id": "friend_bGluemhvdQ",
          "type": "friend",
          "target_id": "linzhou",
          "name": "林舟",
          "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
          "username": "linzhou",
          "member_count": null,
          "is_friend": true,
          "match_field": "message",
          "match_text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
          "message_id": "8601"
        }
      ],
      "limited": false
    }
  }
}

返回对象字段

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

会话、好友或群的搜索分组 · 会话、好友或群的搜索结果 · 消息搜索分组 · 消息搜索分组的结果

会话、好友或群的搜索分组（SearchSection）

字段	类型	说明
items	SearchItem[]	本组最多 20 项。
limited	boolean	true 表示还有未展示的结果。

会话、好友或群的搜索结果（SearchItem）

字段	类型	说明
conversation_id	string	命中对象的会话 ID。
type	string	friend 单聊对象；group 群。
target_id	string	外部 user_id 或公开 group_id。
name	string	当前账号看到的显示名。
avatar	string	头像地址。
username	string | null	用户账号；群或未设置账号时为 null。
member_count	integer | null	群成员数；单聊对象为 null。
is_friend	boolean | null	单聊对象是否为好友；群为 null。
match_field	string	匹配字段：name 名称、remark 备注、account 账号、pinyin 拼音、message 消息。
match_text	string	命中的文字摘要。

消息搜索分组（MessageSearchSection）

字段	类型	说明
items	MessageSearchItem[]	本组最多 20 项，每个会话只给出一条命中的消息。
limited	boolean	true 表示还有未展示的结果。

消息搜索分组的结果（MessageSearchItem）

字段	类型	说明
conversation_id	string	命中对象的会话 ID。
type	string	friend 单聊对象；group 群。
target_id	string	外部 user_id 或公开 group_id。
name	string	当前账号看到的显示名。
avatar	string	头像地址。
username	string | null	用户账号；群或未设置账号时为 null。
member_count	integer | null	群成员数；单聊对象为 null。
is_friend	boolean | null	单聊对象是否为好友；群为 null。
match_field	string	匹配字段：name 名称、remark 备注、account 账号、pinyin 拼音、message 消息。
match_text	string	命中的文字摘要。
message_id	string	命中的消息 ID，可用于定位这条消息。

错误处理

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

返回搜索接口列表 · HTTP 请求约定