文档中心
即时通讯
服务端 API
会话相关
查询单聊会话消息列表

查询单聊会话消息列表

更新时间：2024-03-25 11:40

描述

调用此接口，分页拉取指定用户的某个单聊会话的消息列表。

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=QueryPeerMsg
传输协议：HTTPS
调用频率限制：20次/秒。

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
FromUserId	String	是	如需查询用户 A 与用户 B 的单聊会话消息列表，此处填入用户 A 的 UserID。
ToUserId	String	是	此处填入用户 B 的 UserID。
Limit	Number	否	单次获取消息的数量，取值范围为 (0, 100]，默认为 10。当值 ≤ 0 时，修正为 10。当值 > 100，修正为 100。
Next	Number	否	分页拉取标志，第一次填 0 ，之后填上一次返回的 Next 值。当返回的 Next 为 0 时，代表消息列表获取完毕。例如，当前单聊会话有 250 条消息，调用本接口查询时：第一次调用本接口，Limit 填 100，Next 传 0，查询第 1 ～100 条消息；返回结果中的 Next 值为 num1。第二次调用本接口，Limit 填 100，Next 填 num1，查询第 101 ～ 200 条消息；返回结果中 Next 值为 num2。第三次调用本接口，Limit 填 100，Next 填 num2，查询第 201 ～ 250 条消息；查询完毕，返回结果中的 Next 为 0。
WithEmptyMsg	Number	否	返回结果是否包含已撤回消息和在服务端被删除的消息。 0：默认值，不包含。 1：包含。

FromUserId 和 ToUserId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=QueryPeerMsg
&<公共请求参数>

请求消息体：

{
    "FromUserId": "u1",
    "ToUserId": "u2",
    "Limit": 10,
    "Next": 0,
    "WithEmptyMsg": 0
}

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
Next	Number	分页拉取标志。非 0：表示还有消息未返回，需要将该字段设置到请求参数 Next 中拉取更多消息。为 0：表示已经返回完整消息列表。
List	Number	消息列表。按 MsgTime 降序返回结果。
Sender	String	消息发送者 ID。
MsgType	Number	消息类型： 1：文本。 11：图片。 12：文档。 13：音频。 14：视频。 200：自定义。
SubMsgType	Number	具体的自定义类型。值由用户发送自定义消息时填写，取值范围为 [0,200]。只有当 MsgType 为 200（自定义类型）时，此参数才有意义。
MsgBody	String	消息内容。消息由客户端发送时：当 msg_type 为 1（文本类型）或 200（自定义类型），msg_body 为发送消息时传入的消息内容，开发者可直接阅读消息内容。当 msg_type 为 11、12、13、14，即消息为媒体类型时，msg_body 为 JSON 字符串。请使用 URLDecode 对此 JSON 字符串解码，并按照多媒体消息结构解析这个 JSON 字符串，进而获取消息中的各个字段数据。消息由服务端发送时，不论消息类型，直接返回发送消息时传入的内容。
MsgId	Number	消息 ID，可借此确定消息的唯一性。
MsgSeq	Number	消息 Seq。
Payload	String	消息扩展字段。
MsgTime	Number	服务端收到消息的时间，Unix 时间戳，单位为毫秒（ms）。
IsEmpty	Number	是否是空消息。 0：非空。 1：消息被删除或者已过期。 2：消息被撤回。

msg_body JSON 字符串解析结果参数说明

参数	类型	描述
md5	String	文件的 MD5 值。
file_name	String	文件名称。
file_size	String	文件大小，单位为字节（B）。
download_url	String	下载地址。
media_duration	String	音视频时长，单位为秒（s）。

响应示例

{
    "Code": 0
    "Message": "success",
    "RequestId": "343649807833778782",
    "Next": 1000,
    "List": [
        {
            "Sender": "user1",
            "MsgType": 1,
            "MsgBody": "这是一条消息",
            "MsgId": 971503777289036700,
            "MsgSeq": 1,
            "Payload": "Payload",
            "MsgTime": 1705895412000,
            "IsEempy": 0
        },
        ...
    ]
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000002	输入参数错误。	请检查输入的参数。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试。
660500002	`FromUserId` 未注册。	请检查 `FromUserId` 是否正确。