查询消息

POST

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

本接口支持查询单个指定会话（群聊、单聊）中的多条消息。

注意

本接口的频率限制是 20 条消息/秒，而非 20 次/秒。

Request

Query Parameters

Action string必填

可选值: [QueryMessagesByMsgSeq]

接口原型参数

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

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

用户的 UserID（已在客户端调用 login 方法登录 ZIM 服务，或已调用服务端 API 完成注册）。

查询单聊会话消息时，此处填入任一参与用户的 userID。
查询群聊会话消息时，此处可填入任意已注册用户的 userID。

ConvId string必填

可选值: <= 32 characters

会话 ID。

查询单聊会话消息时，此处填入另一参与用户的 userID（已在客户端调用 login 方法登录 ZIM 服务，或已调用服务端 API 完成注册）。
查询群聊会话消息时，此处填入目标群组的 groupID。

ConvType number必填

可选值: [0, 2]

会话类型：

0：单聊。
2：群聊。

MsgSeqList number[]必填

可选值: <= 20

待查询消息的 seq 列表。列表长度上限为 20。

说明

如需上调，请联系 ZEGO 技术支持。

seq 获取方式：

若需要查询由客户端发出的消息，通过消息发送后回调获取 MsgSeq。
若需要查询由服务端 API SendPeerMessage 发出的单聊消息，通过接口响应数据获取 MsgSeq。
若需要查询由服务端 API SendGroupMessage 发出的群聊消息，通过接口响应数据获取 MsgSeq。

Responses

application/json

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

Schema

Code number

返回码。

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

返回码	说明	处理建议
660000001	服务端出错。	请重试，或联系 ZEGO 技术支持。
660000002	输入的参数缺失或不合法。	请检查输入的参数。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试，或参考相关文档了解调用频率。
660700008	获取用户信息出错。	请检查用户 ID 是否正确。
660700015	用户未注册。	请先注册用户。

Message string

操作结果描述。

RequestId string

请求 ID。

MessageList object[]

返回的消息内容列表。

Array[

Sender string

消息发送者。

MsgType number

消息类型：

1：文本。
10：组合。
11：图片。
12：文件。
13：音频。
14：视频。
31：撤回消息。
32：Tips 消息。
200：自定义。

SubMsgType number

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

MsgBody object

消息内容。

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

anyOf

多媒体消息
组合消息
撤回消息
Tips 消息

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）。

multi_msg object[]

组合消息 Item 数组。

Array[

msg_type integer

可选值: [1, 11, 12, 13, 14, 200]

Item 类型：

1：文本。
11：图片。
12：文档。
13：音频。
14：视频。
200：自定义消息类型。

sub_msg_type integer

仅当 msg_type 为 200 时，返回此参数。

callback_content object

Item 内容。

仅当 msg_type 为 1 或 200 时，可直接在此参数阅读消息内容。
当 Item 为 11、12、13 或 14，请参考多媒体消息结构了解消息的各个字段数据。

]

MsgId number

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

MsgSeq number

消息 seq。

Payload string

消息扩展字段。

MsgTime number

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

IsEmpty number

是否是空消息：

0：不是空消息。
1：消息已被删除（查询不到或者客户调用接口删除此消息），此时其他参数均为空。
2：消息已被撤回。

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "MessageList": [
    {
      "Sender": "userA",
      "MsgType": 1,
      "MsgBody": "this is a message",
      "MsgId": 971503777289036700,
      "MsgSeq": 1,
      "Payload": "this is a payload",
      "MsgTime": 1705895412000,
      "IsEmpty": 0
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "MessageList": [
    {
      "Sender": "userA",
      "MsgType": 1,
      "MsgBody": "this is a message",
      "MsgId": 971503777289036700,
      "MsgSeq": 1,
      "Payload": "this is a payload",
      "MsgTime": 1705895412000,
      "IsEmpty": 0
    }
  ]
}

CURL

ZEGO 签名生成器

AppId

ServerSecret

RESPONSE清除

点击上方 “发送” 按钮，在此处查看响应。