晞晗IM（XHIM）SDK API Reference

想按一个动作查参数和示例？请直接进入 逐个 API 参考。每个公开 API 都有独立 URL，并可在 iOS、macOS、Android、Windows 和 HarmonyOS 之间切换真实公开入口。

面向对象：iOS、macOS、Android、Windows、HarmonyOS、Web、Electron、 Flutter 与小程序开发者

这里是客户端 SDK 的完整公开能力目录。第一次接入仍然从各平台 QuickStart 开始；当你需要查方法、参数、返回模型、事件、错误或扩展点时，再进入本目录。

这不是第一篇教程

如果你还没有完成两个账号互发消息，请先回到 客户端接入总览。如果你准备改页面、UI、Renderer 或业务登录， 先读客户端二次开发指南。本目录用于“查一个准确的 方法和合同”，不要求从头读到尾。

1. 文档导航

你要找什么	文档
创建、连接、登录、续凭、退出、关闭	生命周期与连接
消息、会话、已读、草稿、搜索	消息与会话 API
用户、好友、黑名单、群组、Push	用户、关系链与群组 API
图片、视频、音频、文件、缓存、离线读取	媒体与离线 API
通话信令、RTC Provider 和崩溃恢复	Call Session API
所有事件、回调线程和刷新规则	事件与回调
iOS 的 onSuccess / onFailure 写法	iOS 回调式 API
macOS 的 onSuccess / onFailure 写法	macOS 回调式 API
iOS/macOS 全部异步 API 的 Completion 写法	iOS 回调式 API / macOS 回调式 API
每个回调的载荷、触发条件、线程与重查动作	回调详细说明
公开模型、枚举和稳定错误字段	模型、枚举与错误
自定义消息、Renderer、UI Kit 二次开发	扩展点
语音转文字、消息翻译与客户 Provider	Message Enricher 接入与安全边界
用户与群聊二维码的生成、扫码和安全规则	二维码规范
同一能力在各原生端叫什么	原生平台 API 名称映射
C/C++ 或自研语言 Bridge	xhim_v1 C ABI

平台安装与第一条消息：

• 选择平台与接入说明
• iOS 空白工程
• iOS CocoaPods
• macOS 空白工程
• Android Java/XML（默认）
• Android Kotlin/Compose（兼容）
• Windows 空白工程
• HarmonyOS 空白工程
• Flutter
• React Native
• Unity
• uni-app
• Electron
• Web
• 微信 / 通用小程序

2. 统一调用模型

各原生端语义一致，只有语言习惯不同：

平台	异步调用	事件	普通请求取消
iOS	首选 onSuccess/onFailure；支持 async throws	addEventListener；支持 AsyncStream	XHIMRequest.cancel() 或取消 Swift Task
macOS	首选 onSuccess/onFailure；支持 async throws	addEventListener；支持 AsyncStream	XHIMRequest.cancel() 或取消 Swift Task
Android（默认）	Java CompletableFuture<T>	XHIMJavaEventListener	CompletableFuture.cancel(...)
Android（Kotlin 兼容）	Kotlin suspend	SharedFlow<XHIMEvent>	取消调用它的 Coroutine
Windows	C# Task<T>	IAsyncEnumerable<XHIMEvent>	传入并取消 CancellationToken
HarmonyOS	ArkTS Promise<T>	onEvent 返回退订函数	用 onRequest 取得 requestId 后调用 cancelRequest

除非方法特别注明：

• 可读写 API 需要 Client 已进入 ready；
• 字符串 ID 均不能为空，游标是 SDK 返回的不透明字节，不得自行拼装；
• mutationID 和 clientMessageID 是调用方生成的幂等键，重试时必须复用；
• 时间统一为 Unix Epoch 毫秒；
• 页面层不持有 Token，不直接打开 SDK 数据库；
• Completion 表示这次 API 调用已完成；收到后续事件时仍要重新查询页面数据。

iOS 与 macOS 新项目默认使用同名 onSuccess/onFailure Completion API。 回调按顺序投递到 MainActor，页面和 ViewModel 不需要自行展开 Task 或 do-catch。已有并发封装的项目仍可使用 SDK 的异步重载，但它不是本文档的 默认接入方式。

3. 页面收到事件后怎么处理

连接成功后立即订阅事件
  → 查询会话、消息或联系人
  → 收到变化事件
  → 按事件中的会话或模块重新查询
  → 用完整查询结果更新页面

事件用于提醒页面“数据变了”，不一定包含完整消息。不要只把事件内容追加到列表； 重新查询可以同时处理重复事件、断网恢复和换号后的数据变化。

4. 平台支持与版本兼容

每个 API 页面只展示当前平台真实存在的方法。若当前端未提供高层入口，页面会 明确显示“不支持”，不会给出占位代码。看到 unsupported 时应升级 SDK 或服务端， 不要把它当成空列表或成功结果。

5. 不属于客户端 API 的内容

数据库、对象存储、审核、管理后台、管理员密钥、服务端部署命令和 Endpoint 签名私钥都属于服务端。客户端开发者只配置公开 Server URL、App ID、当前 User ID，并使用业务账号层提供的凭证回调。

服务端接口与运维说明见 XHIM Server，不要把其中的 管理员 API 或密钥复制进 App。