该接口可以根据消息发送者，消息类型以及关键词搜索历史消息。

调用频率

单个应用默认最高调用频率请参考 频控说明。

请求信息

请求 URL

GET https://{endpoint}/im/v2.1/messages/actions/search_messages

请求 URL 中的 {endpoint} 代表服务地址域名，您可以根据用户服务区域选择中国大陆和海外服务地址，并支持搭建高可用主备域名机制。详情请参考 调用方式 服务地址章节。

请求头参数

请求 Header 的参数说明请参考 请求 Header。

查询参数

参数名称	类型	是否必选	说明	示例
operator_id	String	是	操作者账号 ID。	user123
conversation_id	String	否	需要搜索的会话 ID。若不填，则默认搜索全部会话。会话 ID 需要用户自行拼装，拼装规则： sender_id|conversation_type|receiver_id 或 sender_id|conversation_type|team_id sender_id：发送者账号 ID conversation_type：会话类型，1：单聊会话；2：高级群会话；3：超大群会话 receiver_id：接收者账号 ID（单聊对话） team_id：群组 ID（群组会话）	单聊会话：account1|1|account2 高级群会话：account|2|team_id 超大群会话：account|3|team_id
sender_account_ids	String	否	根据消息发送者检索消息，发送者之间用 , 分割，最多支持 5 个，超过将返回参数错误。	sender1,sender2,sender3
message_types	String	否	根据消息类型检索消息，消息类型之间 , 分割。若不填，则默认检索所有消息类型。 支持的消息类型包括： 0：文本；1：图片；2：语音；3：视频；4：地理位置；6：文件；10：提示；12：音视频话单 100：自定义。 关键字（keyword_list）不为空时，不支持检索通知类消息（5）。 如果需要检索非文本消息，需要在消息构造时将需要检索的内容填入 text 字段，否则不会被检索到。	0,1,2,3
message_sub_types	String	否	根据消息子类型检索消息，消息子类型之间 , 分割。若不填，则默认检索所有消息子类型。 关键字（keyword_list）不为空时，不支持检索通知类消息（5）。 如果需要检索非文本消息，需要在消息构造时将需要检索的内容填入 text 字段，否则不会被检索到。	-
start_time	Long	否	检索的起始时间点，UTC 时间戳，单位为毫秒。若未设置，默认表示从现在或从 0 开始搜索。 若检索方向从新到旧，则默认从现在开始。 若检索方向从旧到新， 则默认表示从 0 开始。	-
time_period	Long	否	从起始时间点开始的过去时间范围，单位为毫秒。若未设置表示不限制时间范围。 24x60x60x1000=86400000 表示 1 天。 若检索方向从新到旧，则从startTIme 往更旧的时间查询（startTime - period）。 若检索方向从旧到新，则从startTime 往更新的时间查询（startTime + period）。	86400000
direction	Integer	否	检索方向。0（默认）：从新到旧；1：从旧到新。	0
keyword_list	Array of strings	否	根据关键词检索消息，JSONArray 格式字符串，最多支持 5 个关键词。当消息发送者以及消息类型未设置时，必须设置关键词。	["hello", "world"]
keyword_match_type	Integer	否	关键词匹配类型， 0：或 关系搜索 1：与 关系搜索。当关键词（keyword_list）为空或其数量为 1 时，该字段无效。	0
page_token	String	否	分页标识符，如果为空，则从第一页开始查询。后续传入返回的 next_token。	-
limit	Integer	否	本次检索消息条数上限，最多 100 条。小于等于 0，或者大于 100 会提示参数错误。	100

响应信息

响应头参数

响应 Header 的参数说明请参考 响应 Header。

响应体参数

参数名称	类型	说明	是否必返回
code	Integer	状态码，200 表示请求成功。	是
msg	String	提示信息。请求失败时返回错误信息，请求成功时返回 "success"。	是
- data	Object	返回的 JSON 数据对象，请求失败则返回空对象。	是
count	Integer	搜索到的消息数量。	是
has_more	Boolean	是否还有下一页数据。	是
next_token	String	分页标识符。	否
- items	Array of objects	搜索到的消息列表。	是
message_server_id	Long	服务端消息 ID。	是
conversation_type	Integer	会话类型。1：单聊；2：高级群；3：超大群。	是
sender_id	String	消息发送方账号 ID。	是
message_type	Integer	消息类型。0：文本；1：图片；2：语音；3：视频；4：地址位置；6：文件；10：提示；12：音视频话单；100：自定义。	是
create_time	Long	消息发送时间戳。	是
message_client_id	String	客户端消息 ID。	是
sender_client_type	Integer	消息发送端类型。1：AOS；2：iOS；4：PC；16：Web；32：REST；64：MAC；65：HARMONY。	是
text	String	文本消息内容或多媒体消息的描述文本（该描述信息可用于云端历史消息关键词检索）。	否
attachment	Object	多媒体消息的属性或自定义消息内容。	否
extension	String	消息发送时传入的第三方扩展字段。	否
team_id	Long	群组 ID。team_id 与 receiver_id 只会返回一个。	否
receiver_id	String	消息的接收者 ID。	否
sub_type	Integer	自定义消息子类型，大于 0。message_type = 100 时该字段才有效。	否
modify_account_id	String	消息更新者的用户账号 ID。 只有消息被更新才会返回该字段。	否
modify_time	Long	消息的更新时间。 只有消息被更新才会返回该字段。	否
receiver_account_ids	Array of strings	定向消息接收者账号 ID 列表。	否
inclusive	Boolean	定向消息接收者列表是为可读列表。true（默认）：可读；false：不可读。	否
new_member_visible	Boolean	新进群成员是否可查看该消息。true：可查看；false：不可查看。	否
- thread_config	Object	Thread 消息配置项。	否
- thread_root	Object	Thread 根消息对象。	否
sender_id	String	根消息的发送者。	否
receiver_id	String	根消息的接收者。	否
create_time	Long	根消息的发送时间。	否
message_server_id	Long	根消息的服务器消息 ID。	否
message_client_id	String	根消息的客户端消息 ID。	否
- thread_reply	Object	被回复的消息对象。	否
sender_id	String	被回复消息的发送者。	否
receiver_id	String	被回复消息的接收者。	否
create_time	Long	被回复消息的发送时间。	否
message_server_id	Long	被回复消息的服务器消息 ID。	否
message_client_id	String	被回复消息的客户端消息 ID。	否

响应体示例

JSON{
  "code": 200,
  "msg": "success",
  "data": {
    "count": 3,
    "has_more": false,
    "next_token": "",
    "items": [
      {
        "text": "{\"msg\":\"2025-07-31T16:50:03.534文本消息测试-单聊-检索检索8s4\"}",
        "extension": "ext",
        "message_server_id": 158844553334358020,
        "sender_id": "test36",
        "message_client_id": "7cdb40***e03639c7",
        "conversation_type": 2,
        "team_id": 2366968294,
        "create_time": 1753951805248,
        "message_type": 0,
        "sub_type": 1,
        "receiver_account_ids": [
          "test69"
        ],
        "inclusive": true,
        "new_member_visible": false,
        "modify_account_id": "test36",
        "modify_time": 1753951811315,
        "thread_config": {
          "thread_root": {
            "sender_id": "test36",
            "receiver_id": "2366968294",
            "create_time": 1753951803793,
            "message_server_id": 158844553334358018,
            "message_client_id": "63293***2596b183"
          },
          "thread_reply": {
            "sender_id": "test36",
            "receiver_id": "2366968294",
            "create_time": 1753951803793,
            "message_server_id": 158844553334358018,
            "message_client_id": "63293***596b183"
          }
        },
        "sender_client_type": 32
      }
    ]
  }
}

错误码

本文仅列举部分业务接口错误码，完整列表请参考客户端 API 错误码。

错误码	错误码描述	错误信息示例
200	请求成功	success
414	参数错误	parameter error
102404	用户不存在	account not exist
108404	群不存在	team not exist
108302	非高级群	not advanced team
109404	不是群组成员	not a member
500	服务器内部错误	internal server error