搜索会话消息

在指定会话内搜索聊天记录，结果从新到旧排列，每页最多 20 项。

GET /app/sdk/search/messages

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

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

请求参数

Query

参数	类型	必填	说明
conversation_id	string	是	服务器返回的会话 ID，1–512 字符。
query	string	是	搜索关键词，1–80 字符，不含控制字符。
before_mid	string	否	上一页返回的 next_cursor，正十进制消息 ID 字符串，最多 20 位。首次不传。

请求示例

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

使用说明

• 继续翻页时仍提交相同 conversation_id 和 query，把 next_cursor 作为 before_mid。这里的游标是消息 ID，与目录接口的加密 cursor 不同。
• 打开一条搜索结果时，可使用读取消息接口的 around_mid 定位。

返回参数

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

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

data 字段

字段	类型	说明
conversation_id	string	本次搜索的会话 ID。
query	string	本次搜索关键词。
items	ChatSearchItem[]	命中的消息，从新到旧排列。
next_cursor	string | null	下一页游标；没有下一页时为 null。
has_more	boolean	是否还有下一页。

返回示例

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

{
  "code": 0,
  "msg": "ok",
  "data": {
    "conversation_id": "friend_bGluemhvdQ",
    "query": "海岸",
    "items": [
      {
        "message_id": "8601",
        "sender": {
          "id": "1024",
          "user_id": "chenyue",
          "username": "chenyue",
          "nickname": "陈悦",
          "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
          "signature": "一起发现沿途的风景",
          "profile_updated_at": 1792301400000
        },
        "match_text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
        "created_at": 1792301401000
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

返回对象字段

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

会话内命中的消息 · 用户资料

会话内命中的消息（ChatSearchItem）

字段	类型	说明
message_id	string	消息 ID。
sender	User	发送者资料。
match_text	string	命中文字摘要，最多 200 字。
created_at	integer	消息发送时间，Unix 毫秒时间戳。

用户资料（User）

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

错误处理

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

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