查询单聊会话消息列表

POST

https://zim-api.zego.im/

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

说明

参数 FromUserId 和 ToUserId 对应的用户需已登录或已注册。

说明

调用频率限制：20 次/秒。

Request

Query Parameters

Action string必填

可选值: [QueryPeerMsg]

接口原型参数

https://zim-api.zego.im/?Action=QueryPeerMsg

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

application/json

Body

required

FromUserId string必填

可选值: <= 32 characters

如需查询用户 A 与用户 B 的单聊会话消息列表，此处填入用户 A 的 UserID（已在客户端调用 login 方法登录 ZIM 服务，或已调用服务端 API 完成注册）。

说明

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

ToUserId string必填

可选值: <= 32 characters

此处填入用户 B 的 UserID。

Limit number

可选值: >= 1 and <= 100

默认值: 10

单次获取消息的数量，取值范围为 (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]

默认值: 0

返回结果是否包含已撤回消息和在服务端被删除的消息。

0：默认值，不包含。
1：包含。

Responses

application/json

数据结构
按数据结构生成的示例

Schema

Code number

返回码。

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

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

Message string

请求结果的说明信息。

RequestId string

请求 ID。

Next number

分页拉取标志。

非 0：表示还有消息未返回，需要将该字段设置到请求参数 Next 中拉取更多消息。
为 0：表示已经返回完整消息列表。

说明

除上述说明之外，此字段与列表信息无任何关联，请勿基于此做任何其他逻辑。

List object[]

消息列表。按 MsgTime 降序返回结果。

Array[

Sender string

消息发送者 ID。

MsgType number

消息类型：

1：文本。
10：组合。
11：图片。
12：文档。
13：音频。
14：视频。
200：自定义。

SubMsgType number

具体的自定义类型。值由用户发送自定义消息时填写，取值范围为 [0,200]。只有当 MsgType 为 200（自定义类型）时，此参数才有意义。

MsgBody object

消息内容。

当 MsgType 为 1（文本类型）或 200（自定义类型），MsgBody 为发送消息时传入的消息内容，开发者可直接阅读消息内容。
当 MsgType 为下列类型时，MsgBody 为 JSON 字符串。请使用 URLDecode 对此 JSON 字符串解码，并按照对应结构获取消息中各字段数据：
当 MsgType 为 11、12、13、14（多媒体消息）时，请参考 MsgBody JSON 字符串解析结果的多媒体消息参数说明。
当 MsgType 为 10（组合消息）时，请参考 MsgBody JSON 字符串解析结果的组合消息参数说明。

oneOf

多媒体消息
组合消息

md5 string必填

文件的 MD5 值。

file_name string必填

文件名称。

file_size string必填

文件大小，单位为字节（B）。

download_url string必填

下载地址。

media_duration string

音视频时长，单位为秒（s）。

origin_image_width integer

🏞️如果是图片消息则包含此属性。原图的宽度，单位为像素（px）。

origin_image_height integer

🏞️如果是图片消息则包含此属性。原图的高度，单位为像素（px）。

large_image_download_url string

🏞️如果是图片消息则包含此属性。大图下载地址。

large_image_width integer

🏞️如果是图片消息则包含此属性。大图的宽度，单位为像素（px）。

large_image_height integer

🏞️如果是图片消息则包含此属性。大图的高度，单位为像素（px）。

thumbnail_download_url string

🏞️如果是图片消息则包含此属性。缩略图下载地址。

thumbnail_width integer

🏞️如果是图片消息则包含此属性。缩略图的宽度，单位为像素（px）。

thumbnail_height integer

🏞️如果是图片消息则包含此属性。缩略图的高度，单位为像素（px）。

video_first_frame_download_url string

🎬如果是视频消息则包含此属性。视频首帧图的下载地址。

video_first_frame_width integer

🎬如果是视频消息则包含此属性。视频首帧图的宽度，单位为像素（px）。

video_first_frame_height integer

🎬如果是视频消息则包含此属性。视频首帧图的高度，单位为像素（px）。

MsgId number

消息 ID，可借此确定消息的唯一性。

MsgSeq number

消息 Seq。

Payload string

消息扩展字段。

MsgTime number

服务端收到消息的时间，Unix 时间戳，单位为毫秒（ms）。

IsEmpty number

是否是空消息。

0：非空。
1：消息被删除或者已过期。
2：消息被撤回。

]

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

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