Appearance
getTimeline
最后更新时间 2026-04-17
getTimeline(options) 用于按会话读取消息时间线，并返回当前页消息条目与同步状态。
- 接口标识：
message.getTimeline - 请求类型：
MessageTimelineRequest - 当前状态：可接入
该接口适用于聊天页消息加载、消息翻页和时间线恢复场景。业务方可以通过会话标识和游标按页读取消息内容，而不需要自行拼装底层拉取协议。
注意事项
- 调用前必须已完成 bootstrap 和 login。
- 调用前建议已确认会话存在，必要时可先读取 conversation.getSnapshot。
- cursor 为空时从默认时间线位置开始拉取；后续分页应复用返回的同步标记或游标信息。
- 当前实现阶段为 浅实现，当前可接入状态为 可接入。
- 当前方法已纳入
release/phase0正式发布承诺。
支持说明
该接口用于四端统一的消息时间线读取能力。
| 应用能力 | Android | iOS | Harmony | PC | 发布状态 |
|---|---|---|---|---|---|
| SDK Wrapper | 支持 | 支持 | 支持 | 支持 | 已纳入 release/phase0 |
发布基线：
- android: Android 8.0+ (API 26)
- ios: iOS 15+
- harmony: HarmonyOS NEXT API 12+
- pc: Host OS with supported native bridge runtime
输入
该接口接收 MessageTimelineRequest 请求对象，字段定义如下。
| 名称 | 数据类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
conversation_id | String | 是 | - | 要查询消息时间线的会话标识。 |
cursor | Option<String> | 否 | - | 可选分页游标；为空时从默认时间线位置开始获取。 |
说明
请求对象由业务方传入，用于触发上层 SDK API 调用。平台 wrapper 可以按各自语言习惯封装参数对象，但字段语义必须与 MessageTimelineRequest 保持一致。
输出
该接口成功后返回 MessageTimelineResponse 业务结果，字段定义如下。
| 名称 | 数据类型 | 描述 |
|---|---|---|
conversation_id | String | 当前时间线所属的会话标识。 |
entries | Vec<MessageEntry> | 当前页返回的消息条目列表。 |
total_count | usize | 当前页返回的消息条目数量。 |
timeline_state | String | 时间线状态，例如 ready、empty、stale 或 partial。 |
sync_marker | Option<String> | 用于下一次时间线增量同步的标记。 |
MessageEntry
来源：src/public_api/message/mod.rs
| 名称 | 数据类型 | 描述 |
|---|---|---|
message_id | String | 消息唯一标识。 |
conversation_id | String | 消息所属会话标识。 |
sender_id | String | 消息发送方用户标识。 |
sender_display_name | String | 消息发送方展示名称。 |
message_type | String | 消息类型，例如 text。 |
delivery_state | String | 消息投递或已读状态。 |
content_summary | String | 消息内容摘要，用于列表或时间线预览。 |
timeline_position | String | 消息在时间线中的排序位置标记。 |
source_state | String | 消息内容来源状态，例如 fresh、stale 或 partial。 |
状态与前置条件
- 调用前置条件：
runtime.bootstrap、auth.login - 当前 SDK 状态要求：当前用户会话有效，且目标会话可访问。
- 调用成功后状态：成功后不会改变 SDK 状态，返回当前时间线页结果。
- 建议后续调用：
file.transferPrepare
示例代码
平台调用示例
| 平台 | 正式入口 | 绑定方式 | 错误返回方式 |
|---|---|---|---|
| Android | com.robin.sdk.RobinSdk | kotlin-java-facade | result-error-object |
| iOS | RobinSdk | swift-facade | throws-result-enum |
| Harmony | RobinSdk | arkts-js-facade | result-code-object |
| PC | robin_sdk_bridge | native-bridge-facade | bridge-error-code |
说明
当前仓库尚未提供该方法的真实平台 facade 调用代码片段。你可以先根据以下真实入口信息接入平台 wrapper；后续如补充 docs/examples/<platform>/message-get-timeline.*，页面会自动渲染对应平台示例。
错误码
| 错误码 | 描述 | 排查建议 |
|---|---|---|
action_not_enabled | 当前接口能力未开放，或当前发布范围不支持该调用。 | 检查接口是否已纳入当前发布范围，并确认目标平台已支持该能力。 |