主题
用户、关系链与群组 API
1. 用户资料
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
user.current_profile | 获取当前用户资料 | 无 | XHIMUserProfile |
user.batch_profiles | 批量获取用户资料 | userIDs | XHIMUserProfileBatch |
user.update_profile | 更新当前用户资料 | XHIMUserProfileUpdate | XHIMUserProfile |
XHIMUserProfileBatch 同时返回找到的资料和缺失 ID；批量查询方必须按 userID 关联结果，不能依赖返回顺序。显示名称和头像采用服务端返回值，客户端不再叠加 一套独立缓存优先级。
XHIMUserProfileUpdate 的可选字段表示“是否修改”，空字符串是一个明确值。 修改成功后以返回的完整 Profile 替换本地 UI，不要拼接旧值。
2. 好友申请和好友关系
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
relationship.send_friend_request | 发起好友申请 | toUserID, introduction, mutationID | XHIMFriendRequest |
relationship.resolve_friend_request | 接受或拒绝 | requestID, decision, mutationID | XHIMFriendRequestResolution |
relationship.delete_friendship | 删除好友关系 | peerUserID, mutationID | XHIMFriendshipDeletion |
relationship.set_friend_remark | 设置好友备注 | peerUserID, remark, expectedRevision, mutationID | XHIMFriendRemarkChange |
relationship.list_friend_requests | 分页查询好友申请 | 可选 cursor, limit | XHIMSocialPage<XHIMFriendRequest> |
relationship.list_friendships | 分页查询好友 | 可选 cursor, limit | XHIMSocialPage<XHIMFriendship> |
decision 只有 accept 和 reject。同一 mutationID 重放返回相同业务结果； 使用不同 mutation ID 重复处理已经完成的申请，会得到稳定冲突或状态错误。
备注是好友关系的服务端字段。UI 展示时直接使用返回的 remark / display 字段，不在另一个本地 Store 中覆盖服务端结果。
3. 黑名单
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
relationship.set_block | 添加或解除拉黑 | blockedUserID, isActive, mutationID | XHIMBlock |
relationship.list_blocks | 分页查询黑名单 | 可选 cursor, limit | XHIMSocialPage<XHIMBlock> |
解除拉黑使用同一个 setBlock，并把 isActive 设为 false。拉黑是否同时阻止 历史消息、好友申请或群内互动由部署方服务端策略决定；客户端只根据返回和稳定 错误展示结果。
4. 群组生命周期
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
group.create | 创建群组 | title, memberUserIDs, mutationID | XHIMGroupChange |
group.change_members | 增删成员 | conversationID, addUserIDs, removeUserIDs, expectedRevision, mutationID | XHIMGroupChange |
group.leave | 当前用户退群 | conversationID, expectedRevision, mutationID | XHIMGroupLifecycleResult |
group.dismiss | 群主解散群 | conversationID, expectedRevision, mutationID | XHIMGroupLifecycleResult |
changeGroupMembers 是一个原子变更。同一用户不能同时出现在 add/remove； 接入层应在调用前去重。成员权限、群容量和是否允许直接邀请由服务端校验，客户端 不要把按钮可见性当成权限证明。
5. 入群申请
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
group.request_join | 申请加入群组 | conversationID, introduction, mutationID | XHIMGroupJoinMutation |
group.resolve_join | 管理员接受或拒绝 | requestID, decision, mutationID | XHIMGroupJoinMutation |
group.list_join_requests | 分页查询入群申请 | 可选 cursor, limit | XHIMSocialPage<XHIMGroupJoinRequest> |
群设置为无需审批时，服务端可以直接完成加入；客户端仍以返回的 XHIMGroupJoinMutation 和后续群成员投影为准。
6. 群治理
group.change_governance
统一输入：
conversationIDexpectedRevisionmutationIDchange: XHIMGroupGovernanceChange
支持的强类型变更：
| change | 参数 | 说明 |
|---|---|---|
setAdministrator | userID, isAdministrator | 设置或取消管理员 |
setMute | userID, 可选 mutedUntilMilliseconds | nil / 空值解除禁言 |
transferOwnership | toUserID | 转让群主 |
setJoinApprovalRequired | Bool | 开关入群审批 |
setProfile | title, avatarURL, announcement, description | 原子更新群资料 |
返回 XHIMGroupChange。群角色和 revision 可能同时改变，成功后应重新查询群资料 与成员列表。
7. 群查询
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
group.list | 分页查询当前用户群组 | 可选 cursor, limit | XHIMSocialPage<XHIMGroup> |
group.list_members | 分页查询成员 | conversationID, 可选 cursor, limit | XHIMSocialPage<XHIMGroupMember> |
成员页包含群 revision fence。跨多页渲染时，如果后续页 revision 与第一页不 一致，应丢弃这一轮结果并从第一页重新读取，避免把成员变更前后的数据拼在一起。
8. Presence 和正在输入
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
user.publish_presence | 发布在线状态 | XHIMPresenceStatus, ttlMilliseconds | XHIMPresencePublication |
user.publish_typing | 发布输入状态 | conversationID, isTyping, ttlMilliseconds | XHIMTypingPublication |
Presence 和 Typing 是短暂状态，不进入可靠消息历史。接收方必须按 expiresAtMilliseconds 本地过期；“停止输入/离线”帧可能因断网丢失。
9. Push 设备
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
push.register | 注册或轮换 Push Token | XHIMPushDevice | XHIMPushDeviceRegistration |
push.disable | 禁用当前设备 Push | deviceID | XHIMPushDeviceDisableResult |
XHIMPushDevice 包含 platform、deviceID、token、environment 和 locale。Token 只作为输入，错误、日志、description 和诊断不会回显。APNs/FCM/Huawei 厂商 凭证配置在服务端，不放进 SDK 客户端。
10. 多端登录设备
| api-id | 用途 | 主要输入 | 返回 |
|---|---|---|---|
session.list | 列出当前账号设备会话 | 无 | XHIMDeviceSessionPage |
session.revoke | 撤销一个设备会话 | sessionID, mutationID | XHIMDeviceSessionRevocation |
XHIMDeviceSessionPolicy 描述部署方的多端登录策略和设备上限。撤销当前会话可能 立即触发凭证失效或登出；接入方应在账号容器统一处理状态事件。
11. 社交列表刷新
收到 socialChanged 时按 socialScope 重新查询对应列表：
| scope | 重查方法 |
|---|---|
friendRequests | friendRequests |
friendships | friendships |
groups | groups |
groupMembers | 当前 scope ID 的 groupMembers |
blocks | blocks |
groupJoinRequests | groupJoinRequests |
unknown scope 或 requiresFullRequery == true 时，刷新当前页面依赖的全部社交 投影，不尝试解析未知数字值。