读取消息

读取最新消息、向前或向后翻页，或者定位到指定消息附近。每次最多返回 30 条消息。

GET /app/sdk/messages

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数

Query

参数	类型	必填	说明
`conversation_id`	string	是	服务器返回的会话 ID，1–512 字符。
`before_seq`	string	否	读取此序号之前的消息，正十进制字符串，最多 19 位。与其他定位或校准参数互斥。
`after_seq`	string	否	读取此序号之后的消息，非负十进制字符串，最多 19 位。与其他定位或校准参数互斥。
`around_mid`	string	否	定位到此消息附近，正十进制消息 ID，最多 19 位。与其他定位或校准参数互斥。
`known_last_seq`	string	否	本地已知最新序号，非负十进制字符串，最多 19 位；下面三项校准参数必须一起提交。
`known_updated_at`	string	否	本地已知会话更新时间，非负毫秒整数的十进制字符串，最多 19 位。
`known_deletion_revision`	string	否	本地已知本人删除版本号，非负整数的十进制字符串，最多 19 位。

请求示例

bash

curl -G 'https://example.com/app/sdk/messages' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  --data-urlencode 'conversation_id=friend_bGluemhvdQ'

使用说明

首次读取只传 conversation_id。向前翻页时把 page.start_seq 作为 before_seq；向后翻页时把 page.end_seq 作为 after_seq。
序号是消息在当前会话内的位置，mid 是消息的唯一 ID，两者不能混用。
三个 known_* 参数用于检查本地窗口是否仍有效。page.mode=unchanged 时 conversation=null、messages=[]，保留现有消息即可；mode=reset 时用返回窗口更新本地内容。
已撤回或被本人删除的消息仍保留原 ID 和序号，正文等内容字段为 null。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
`code`	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
`msg`	string	成功通常为 ok，失败时为错误说明。
`data`	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
`conversation`	Conversation \| null	当前会话；page.mode=unchanged 时为 null。
`messages`	Message[]	本次窗口的消息，按会话序号从小到大排列。
`deletion_revision`	integer	当前账号删除记录的版本号。用于检查本地删除状态是否需要更新。
`page`	Page	窗口类型与翻页位置。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

展开完整返回示例

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "conversation": {
      "conversation_id": "friend_bGluemhvdQ",
      "type": "friend",
      "target_id": "linzhou",
      "name": "林舟",
      "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
      "member_count": null,
      "group_role": null,
      "all_muted": false,
      "send_forbidden_until": 0,
      "last_mid": "8601",
      "last_seq": "18",
      "read_seq": "18",
      "peer_read_seq": "17",
      "announcement_updated_at": 0,
      "announcement_unread": false,
      "mention_unread": false,
      "updated_at": 1792301401000,
      "last_message_time": 1792301401000,
      "last_message": {
        "mid": "8601",
        "conversation_seq": "18",
        "sender_id": "chenyue",
        "sender_name": null,
        "type": "text",
        "status": "normal",
        "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
        "file_name": null,
        "created_at": 1792301401000,
        "updated_at": 1792301401000
      },
      "unread_count": 0,
      "pinned": false,
      "muted": false,
      "state": "chatting",
      "peer": {
        "id": "1025",
        "user_id": "linzhou",
        "username": "linzhou",
        "nickname": "林舟",
        "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
        "signature": "把每一次出发安排妥当",
        "profile_updated_at": 1792301400000
      },
      "peer_presence": {
        "online": true,
        "online_updated_at": 1792301400000
      }
    },
    "messages": [
      {
        "mid": "8601",
        "client_message_id": "outing-20261018-01",
        "conversation_id": "friend_bGluemhvdQ",
        "conversation_seq": "18",
        "sender_id": "chenyue",
        "sender": {
          "id": "1024",
          "user_id": "chenyue",
          "username": "chenyue",
          "nickname": "陈悦",
          "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
          "signature": "一起发现沿途的风景",
          "profile_updated_at": 1792301400000
        },
        "type": "text",
        "status": "normal",
        "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
        "mentions": null,
        "media": null,
        "contact": null,
        "system": null,
        "quote": null,
        "recalled_by": null,
        "recalled_at": null,
        "deleted_at": null,
        "created_at": 1792301401000,
        "updated_at": 1792301401000
      }
    ],
    "deletion_revision": 0,
    "page": {
      "mode": "latest",
      "has_older": false,
      "has_newer": false,
      "start_seq": "18",
      "end_seq": "18",
      "anchor_mid": null
    }
  }
}

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

会话 · 最后一条消息摘要 · 用户资料 · 在线状态 · 群资料 · 完整消息 · @ 提醒 · 媒体资源 · 用户名片 · 系统消息内容 · 引用消息摘要 · 消息窗口与翻页信息

会话（Conversation）

字段	类型	说明
`conversation_id`	string	会话 ID。读取消息、发送消息和修改会话状态时直接使用此值。
`type`	string	friend 表示单聊，group 表示群聊。
`target_id`	string	单聊为对方的外部 user_id；群聊为公开 group_id。
`name`	string	当前账号看到的会话名称，可能已应用个人备注。
`avatar`	string	会话头像地址。
`member_count`	integer \| null	群成员数；单聊为 null。
`group_role`	string \| null	本人在群中的角色：owner 群主、admin 管理员、member 成员；单聊为 null。
`all_muted`	boolean	群是否开启全员禁言；单聊为 false。
`send_forbidden_until`	integer	本人禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。
`last_mid`	string	最新消息 ID；没有消息时为 "0"。
`last_seq`	string	最新消息序号；没有消息时为 "0"。
`read_seq`	string \| null	本人已读到的消息序号。未提供个人状态的共享事件可为 null。
`peer_read_seq`	string \| null	单聊对方已读到的序号；群聊为 null。
`announcement_updated_at`	integer	群公告更新时间；单聊为 0，Unix 毫秒时间戳。
`announcement_unread`	boolean	本人是否有未读群公告；单聊为 false。
`mention_unread`	boolean	是否存在尚未读到的群内 @ 提醒；单聊为 false。
`updated_at`	integer	会话最后更新时间，Unix 毫秒时间戳。
`last_message_time`	integer	最新消息时间；没有消息时为 0，Unix 毫秒时间戳。
`last_message`	LastMessage \| null	最后一条消息摘要；没有消息时为 null。
`unread_count`	integer	本人未读消息数，范围 0–100；100 表示至少 100 条。
`pinned`	boolean	本人是否置顶。
`muted`	boolean	本人是否开启免打扰。
`state`	string	chatting 表示显示在会话列表，hidden 表示隐藏。
`peer`	User	仅单聊返回，对方完整资料；群聊不返回此字段。
`peer_presence`	Presence \| null	单聊对方在线状态；群聊或暂时没有状态时为 null。
`group`	Group	仅群聊返回，完整群资料；单聊不返回此字段。

最后一条消息摘要（LastMessage）

字段	类型	说明
`mid`	string	消息 ID。
`conversation_seq`	string	这条消息在当前会话中的序号。
`sender_id`	string \| null	发送者的外部 user_id；系统消息为 null。
`sender_name`	string \| null	群消息发送者的显示名；单聊中可为 null。
`type`	string	text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。
`status`	string	normal 正常、recalled 已撤回、deleted 已被当前账号删除。
`text`	string \| null	文字或摘要文本；没有文本、已撤回或已删除时为 null。
`file_name`	string \| null	文件名称；非文件消息或内容已清除时为 null。
`created_at`	integer	发送时间，Unix 毫秒时间戳。
`updated_at`	integer	消息最后更新时间，Unix 毫秒时间戳。

用户资料（User）

字段	类型	说明
`id`	string	IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
`user_id`	string	宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
`username`	string \| null	可用于精确搜索的账号；没有设置时为 null。
`nickname`	string	显示昵称。
`avatar`	string	头像地址。
`signature`	string	个性签名；未设置时为空字符串。
`profile_updated_at`	integer	公开资料最后更新时间，Unix 毫秒时间戳。

在线状态（Presence）

字段	类型	说明
`online`	boolean	当前是否在线。
`online_updated_at`	integer	在线状态最后更新时间，Unix 毫秒时间戳。

群资料（Group）

字段	类型	说明
`group_id`	string	公开群 ID，群相关请求使用这个值。
`owner_id`	string	群主的外部 user_id。
`name`	string	群名称。
`avatar`	string	群头像地址。
`avatar_custom`	boolean	是否由用户上传头像；false 表示服务器生成的组合头像。
`announcement`	string \| null	群公告正文；没有公告时为 null。
`announcement_author_id`	string \| null	最近一次公告发布者的外部 user_id；没有公告时可为 null。
`announcement_author_name`	string \| null	公告发布者的显示名；没有公告时可为 null。
`announcement_updated_at`	integer	公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
`status`	string	群状态：active 正常、disabled 停用、dissolved 已解散。
`all_muted`	boolean	是否开启全员禁言。
`join_approval_required`	boolean	扫码加入是否需要群主或管理员审批。
`member_count`	integer	当前成员人数。
`unread_mode`	string	未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
`last_mid`	string	最新消息 ID；还没有消息时为 "0"。
`last_seq`	string	最新消息在群内的序号；没有消息时为 "0"。
`last_message_at`	integer	最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
`conversation_updated_at`	integer	群会话内容最后更新时间，Unix 毫秒时间戳。
`created_at`	integer	建群时间，Unix 毫秒时间戳。
`updated_at`	integer	群资料最后更新时间，Unix 毫秒时间戳。

完整消息（Message）

字段	类型	说明
`mid`	string	服务器分配的消息 ID。
`client_message_id`	string \| null	发送时提交的去重 ID；只有原发送者能看到，其他用户为 null。
`conversation_id`	string	消息所属会话 ID。
`conversation_seq`	string	消息在该会话中的递增序号。用于前后翻页，不能用 mid 代替。
`sender_id`	string \| null	发送者的外部 user_id；系统消息为 null。
`sender`	User \| null	发送者资料；系统消息为 null。
`type`	string	text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。
`status`	string	normal 正常、recalled 已撤回、deleted 已被当前账号删除。
`text`	string \| null	文字正文；其他类型或内容已清除时为 null。
`mentions`	Mentions \| null	群文字消息的 @ 提醒；无提醒或内容已清除时为 null。
`media`	Media \| null	图片、语音、视频、文件的资源信息；其他类型或内容已清除时为 null。
`contact`	ContactCard \| null	名片内容；其他类型或内容已清除时为 null。
`system`	SystemMessage \| null	系统提示内容；非系统消息或内容已清除时为 null。
`quote`	Quote \| null	引用消息的展示摘要；没有引用或内容已清除时为 null。
`recalled_by`	string \| null	撤回者的外部 user_id；未撤回或已删除时为 null。
`recalled_at`	integer \| null	撤回时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
`deleted_at`	integer \| null	当前账号删除此消息的时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
`created_at`	integer	发送时间，Unix 毫秒时间戳。
`updated_at`	integer	消息最后更新时间，Unix 毫秒时间戳。

@ 提醒（Mentions）

字段	类型	说明
`type`	string	all 表示所有人；users 表示指定成员。
`user_ids`	string[]	仅 type=users 时返回，目标成员的外部 user_id 列表；type=all 时不返回。

媒体资源（Media）

字段	类型	说明
`url`	string	原资源地址。发送媒体消息时原样使用上传接口给出的地址。
`thumbnail_url`	string \| null	图片缩略图或视频封面地址；没有缩略图时为 null。
`mime_type`	string	资源的 MIME 类型，例如 image/webp。
`file_name`	string \| null	原文件名称；不适用时为 null。
`size`	integer	资源大小，单位为字节。
`width`	integer \| null	图片或视频宽度，单位为像素；不适用或未提供时为 null。
`height`	integer \| null	图片或视频高度，单位为像素；不适用或未提供时为 null。
`duration_ms`	integer \| null	媒体时长，单位为毫秒；不适用或尚未解析时为 null。当前视频上传结果的此项为 null。

用户名片（ContactCard）

字段	类型	说明
`user_id`	string	名片所属用户的外部 user_id。
`nickname`	string	名片昵称。
`avatar`	string \| null	名片头像地址；没有头像时可为 null。

系统消息内容（SystemMessage）

字段	类型	说明
`code`	string	系统事件类型，例如群成员变化。
`text`	string	可直接展示的说明文本。
`params`	object	随事件类型变化的补充信息；没有统一固定字段。展示提示时优先使用 text。

引用消息摘要（Quote）

字段	类型	说明
`mid`	string	被引用消息 ID。
`sender_id`	string	原发送者的外部 user_id。
`sender_name`	string	原发送者显示名。
`type`	string	原消息类型：text、image、voice、video、file、contact。
`preview`	string \| null	最多 160 字的展示摘要。文字消息有文本；文件或名片可有摘要；图片、语音、视频为 null。

消息窗口与翻页信息（Page）

字段	类型	说明
`mode`	string	latest 最新消息、before 更早消息、after 更晚消息、around 指定消息附近、reset 需要替换本地窗口、unchanged 本地窗口仍有效。
`has_older`	boolean	窗口前方是否还有更早的消息。
`has_newer`	boolean	窗口后方是否还有更新的消息。
`start_seq`	string \| null	窗口第一条消息序号；继续向前翻页时作为 before_seq。没有消息时为 null。
`end_seq`	string \| null	窗口最后一条消息序号；继续向后翻页时作为 after_seq。没有消息时为 null。
`anchor_mid`	string \| null	定位窗口的消息 ID；不适用时为 null。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回消息接口列表 · HTTP 请求约定

用户预置与 Token

首页与会话

消息

上传与下载

用户、好友与申请

群与成员

搜索

音视频通话

随附宿主账号

设备与推送

举报与诊断

读取消息

请求参数

Query

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

会话（Conversation）

最后一条消息摘要（LastMessage）

用户资料（User）

在线状态（Presence）

群资料（Group）

完整消息（Message）

@ 提醒（Mentions）

媒体资源（Media）

用户名片（ContactCard）

系统消息内容（SystemMessage）

引用消息摘要（Quote）

消息窗口与翻页信息（Page）

错误处理

读取消息 ​

请求参数 ​

Query ​

请求示例 ​

使用说明 ​

返回参数 ​

data 字段 ​

返回示例 ​

返回对象字段 ​

会话（Conversation） ​

最后一条消息摘要（LastMessage） ​

用户资料（User） ​

在线状态（Presence） ​

群资料（Group） ​

完整消息（Message） ​

@ 提醒（Mentions） ​

媒体资源（Media） ​

用户名片（ContactCard） ​

系统消息内容（SystemMessage） ​

引用消息摘要（Quote） ​

消息窗口与翻页信息（Page） ​

错误处理 ​

读取消息

请求参数

Query

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

会话（Conversation）

最后一条消息摘要（LastMessage）

用户资料（User）

在线状态（Presence）

群资料（Group）

完整消息（Message）

@ 提醒（Mentions）

媒体资源（Media）

用户名片（ContactCard）

系统消息内容（SystemMessage）

引用消息摘要（Quote）

消息窗口与翻页信息（Page）

错误处理