服务端 API

迁移到 OpenIM

迁移到 OpenIM 时，建议把已有系统的数据先整理成 OpenIM 的用户、关系、群组、会话和消息模型，再由可信后端按批次调用 Platform API。迁移过程不应该由客户端执行；管理员 Token、批量导入脚本、失败重试和审计日志都应保留在服务端。

能力范围

原系统数据	OpenIM 中的目标能力	说明
账号与资料	用户	先注册用户，再补齐昵称、头像和扩展字段。
好友关系	关系	使用好友导入能力写入已有关系，黑名单按关系模块单独导入。
群与成员	群组	先创建群组，再邀请或导入成员，并按需要设置群资料。
历史消息	消息	按会话、发送者、时间和消息类型整理后，通过服务端消息能力写入或补发。
会话状态	会话	迁移后再处理置顶、免打扰、未读和离线推送等用户会话状态。

迁移任务	主要接口	使用建议
注册用户	创建用户	用业务账号 ID 作为 OpenIM `userID`，避免迁移后再做 ID 映射。
查询用户	查询用户列表	分批校验用户是否已经写入 OpenIM。
导入好友	导入好友	适合把历史好友关系直接写入，不建议逐个走好友申请流程。
创建群组	创建群组	迁移群时先确定群 ID、群主、群名称和初始成员策略。
邀请成员	邀请用户进群	已有群成员可按批次加入，注意控制单次请求规模。
发送或导入消息	发送单条消息	历史消息迁移应由后端模拟原发送者写入，并保留原始发送时间。
批量发送消息	批量发送消息	适合系统通知或低风险批量补发，历史消息仍要先做顺序和幂等设计。

推荐按用户、关系、群组、消息、会话校验的顺序迁移。先确保每个业务账号都有稳定的 OpenIM userID；导入好友关系和黑名单前，确认双方用户都已经存在；迁移群组时先创建群，再导入成员和群资料；迁移消息时按会话维度分批写入历史消息，并保留原始消息 ID、发送时间和迁移批次号。

迁移脚本应设计为可重复执行。每批数据都应记录源系统主键、OpenIM 目标 ID、操作时间、operationID、返回结果和错误原因；失败后只重试失败记录，避免重复创建用户、重复导入好友或重复写入消息。

历史消息迁移要特别关注顺序和幂等。建议按会话拆分批次，并在业务扩展字段中保留源消息 ID 或迁移批次号。迁移前先在测试环境验证消息类型映射、撤回状态、文件地址和离线推送策略。

OpenIM 的会话未读数由消息序列和用户已读序列计算得到。迁移历史消息时，单纯导入消息只能恢复消息内容、发送者和发送时间，不能自动恢复每个用户在每个会话中的已读位置。

当前版本的公开 Platform API 还没有直接提供“批量将历史会话标记为已读”或“按会话设置未读数”的接口。迁移项目如果需要处理未读数，建议在方案评估阶段先确认源系统是否能导出用户级会话阅读状态，再选择迁移策略。

策略	说明	适用场景
历史消息默认已读	迁移完成后，将导入的历史会话视为已读，避免用户首次登录 OpenIM 时出现大量历史未读。	源系统无法提供用户级阅读状态，或业务希望迁移完成后从新消息开始重新计算未读数。
按用户会话恢复未读数	由业务方提供每个用户在每个会话中的未读数，OpenIM 根据会话最新消息序列反推已读位置。	源系统能够导出 `userID + conversationID + unreadCount`，且业务要求尽量保留迁移前的未读体验。

对于有未读状态迁移要求的项目，OpenIM 可根据迁移需求补充对应的数据修正或 Platform API 能力，例如：

如果源系统无法提供用户级阅读状态，OpenIM 无法仅根据历史消息准确还原未读数。此时更推荐将迁移前历史消息默认视为已读，并从迁移完成后的新消息开始重新计算未读数。