Skip to main content

获取消息

接口概述​

该接口用于获取消息历史记录，使用cursor分页。请求时需要提供有效的 access_token。

该接口需要chat权限

接口 URL

GET https://ydzx.panretro.com/external/api/v1/im/getMessage

请求参数

参数名类型必填描述
access_tokenstring是OAuth2 授权访问令牌，用于验证用户身份
groupIdlong是聊天室ID
groupTypeint是聊天室类型
cursorlong否分页游标（基于消息数据库 id，首次不传默认获取最新消息）
pageSizeint否(默认10)返回数据的条数

注意：access_token 必须有效，否则接口会返回授权失败。

分页说明​

分页通过 cursor（基于消息数据库 id）实现。首次请求不传 cursor（默认获取最新消息），响应中返回 nextPageCursor 和 previousPageCursor，分别用于向前/向后翻页。

messageId 为消息的业务 ID，id 为消息的数据库主键（即 cursor 的值），createTime 为消息的创建时间戳（毫秒）。

响应说明​

接口返回 JSON 格式数据，主要字段如下：

响应示例​

{
  "code": 200,
  "msg": "success",
  "data": {
    "currentPage": 1,
    "totalPage": 129,
    "nextPageCursor": "42",
    "previousPageCursor": null,
    "groupMessages": [
      {
        "groupId": 1595038762,
        "groupType": 0,
        "userId": "2246656429",
        "type": 0,
        "content": "[{\"text\": {\"text\": \"hello\"}}, {\"at\": {\"qq\": \"3927731416\", \"name\": \"Alice\"}}]",
        "pinyin": "[{\"text\": {\"text\": \"hello\"}}, {\"at\": {\"qq\": \"3927731416\", \"name\": \"Alice\"}}]",
        "groupName": "远东在线小测",
        "groupNamePinyin": "yuan3 dong1 zai4 xian4 xiao3 ce4",
        "messageId": 42,
        "createTime": 1761655372732,
        "receiveTime": "Tue Oct 28 20:42:52 CST 2025",
        "nickname": "IBM-找平面设计师",
        "nicknamePinyin": "IBM-zhao3 ping2 mian4 she4 ji4 shi1",
        "avatar": "/api/avatar/get/QQpersonal?id=2246656429"
      }
    ]
  }
}

响应字段说明​

字段名类型描述
codeint状态码，200 表示请求成功
msgstring返回信息，成功时为 "success"
data.currentPageint当前游标的页数
data.totalPageint总页数
data.nextPageCursorstring(nullable)下页游标（消息数据库 id）
data.previousPageCursorstring(nullable)上页游标（消息数据库 id）
data.groupMessagesArray: MessageDto消息列表

MessageDto​

字段名类型描述
groupIdlong聊天室ID
groupTypeint聊天室类型
userId(String) long用户ID
typeint消息类型
contentString消息内容 JSON 数组，格式见 MessageContent
messageIdlong消息数据库主键 id
createTimelong消息创建时间戳（毫秒）
receiveTime(String) DateTime收到消息的时间
nicknameString昵称
nicknamePinyinString昵称拼音（带数字声调，如 "IBM-zhao3 ping2 mian4 she4 ji4 shi1"），方便英文用户阅读
avatarString (nullable)头像路径（QQ: /api/avatar/get/QQpersonal?id={qq}，远东: /api/avatar/get/personal?id={userId}）
pinyinString消息内容的拼音版本，格式同 content，但 text 段中的中文已转为带数字声调的拼音
groupNameString群组名称
groupNamePinyinString群组名称拼音（带数字声调），方便英文用户阅读

MessageContent​

content 为 JSON 数组字符串，每个元素是一种消息段：

{"消息类型": {"参数": "值"}}

格式符合OneBot12标准

目前支持以下消息段：

  • 纯文本消息
[{"text": {"text": "早上好"}}]
  • 纯图片消息
[{"image": {"file": "E171C1C7DCB8205A99638929FD1D004F.jpg", "summary": "", "sub_type": "0", "file_size": "1491524"}}]

图片Url如下：

长宽最高为128像素的图片: http://ydzx.panretro.com/download/128_E171C1C7DCB8205A99638929FD1D004F.jpg

原始大小的图片: http://ydzx.panretro.com/download/E171C1C7DCB8205A99638929FD1D004F.jpg

图片会定时清理，请求返回可能为404或为默认的noimage.gif

  • @提及消息
[{"at": {"qq": "3927731416", "name": "Alice"}}]

qq 为被提及的 QQ 号，name 为服务端从数据库自动补充的群名片名称。"qq": "all" 时为 @全体成员。

  • 回复消息
[{"reply": {"id": "658617555", "messageId": "42"}}]

id 为机器人消息 ID（message_id 列），messageId 为被回复消息的数据库主键 id。

  • 文件消息（本地/WebSocket 上传）
[{"file": {"relativePath": "123/abc/file.pdf", "isQQ": "0"}}]

relativePath 为相对于存储根目录的路径，isQQ 为 "1" 时表示 QQ 群文件。下载 URL：/downloadFile/{base64path}/{qq|local}/{safeName}。

注意：QQ 同步的文件消息仅含 file 键（如 [{"file": {"file": "xxx"}}]），无 relativePath，此类消息显示为"该信息不支持"。

示例​

获取类型为0聊天室ID为891349568的最新十条消息：

http://localhost:8080/external/api/v1/im/getMessage?
        groupId=891349568&
        groupType=0&
        access_token=kwc2esQuWTRoSjAfWrkcjicoORVLrMNguHanf0Uv0mT4A6KPrDJzfvZ47JBB

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "currentPage": 1,
    "totalPage": 129,
    "nextPageCursor": "17611422717776693",
    "previousPageCursor": null,
    "groupMessages": [
      {
        "groupId": 1595038762,
        "groupType": 0,
        "userId": "2246656429",
        "type": 0,
        "content": "[{\"text\": {\"text\": \"有人吗?\"}}, {\"at\": {\"qq\": \"3927731416\", \"name\": \"Alice\"}}]",
        "messageId": 42,
        "createTime": 1761655372732,
        "receiveTime": "Tue Oct 28 20:42:52 CST 2025",
        "nickname": "IBM-找平面设计师",
        "avatar": "/api/avatar/get/QQpersonal?id=2246656429"
      }
    ]
  }
}

获取类型为0聊天室ID为891349568的最新的20条消息：

http://localhost:8080/external/api/v1/im/getMessage?
        groupId=891349568&
        groupType=0&
        access_token=kwc2esQuWTRoSjAfWrkcjicoORVLrMNguHanf0Uv0mT4A6KPrDJzfvZ47JBB&
        pageSize=20

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "currentPage": 1,
    "totalPage": 65,
    "nextPageCursor": "17595180777389728",
    "previousPageCursor": null,
    "groupMessages": [
      {
        "groupId": 1595038762,
        "groupType": 0,
        "userId": "2246656429",
        "type": 0,
        "content": "[{\"text\": {\"text\": \"hello\"}}]",
        "messageId": 43,
        "createTime": 1761655372732,
        "receiveTime": "Tue Oct 28 20:42:52 CST 2025",
        "nickname": "IBM-找平面设计师",
        "avatar": "/api/avatar/get/QQpersonal?id=2246656429"
      }
    ]
  }
}

获取上一个响应的下一页20条消息：

http://localhost:8080/external/api/v1/im/getMessage?
        groupId=891349568&
        groupType=0&
        access_token=kwc2esQuWTRoSjAfWrkcjicoORVLrMNguHanf0Uv0mT4A6KPrDJzfvZ47JBB&
        cursor=17611422717776693&
        pageSize=20

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "currentPage": 2,
    "totalPage": 65,
    "nextPageCursor": "17595180014231042",
    "previousPageCursor": "17616553727329349",
    "groupMessages": [
      {
        "groupId": 1429052476,
        "groupType": 0,
        "userId": "2246656429",
        "type": 0,
        "content": "[{\"text\": {\"text\": \"我很想知道这是磁条还是伪装成磁条的黑色墨水\"}}]",
        "messageId": 44,
        "createTime": 1761142164290,
        "receiveTime": "Wed Oct 22 22:09:24 CST 2025",
        "nickname": "IBM-找平面设计师",
        "avatar": "/api/avatar/get/QQpersonal?id=2246656429"
      }
    ]
  }
}

此时，想要查看上一页(第一页)，设置cursor为17616553727329349，查看下一页(第三页),设置cursor为17595180014231042