查询单聊会话消息列表

描述

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

接口原型

请求方法：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 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，''，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

Untitled

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

Copied!

请求消息体：

Untitled

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

Copied!

响应参数

参数	类型	描述
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）。

响应示例

Untitled

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

Copied!

返回码

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

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