为单聊创建多个会话
功能简介
在 ZIM 中,单聊会话的会话 ID(conversationID)默认为对方的 userID,因此两个用户之间只能存在一个单聊会话。
自 3.2.0 版本起,ZIM 支持为同一对用户创建多个相互独立的单聊会话。支持自定义会话 ID ,不再与对方的 userID 绑定。每个会话拥有独立的消息记录、消息未读数和会话设置,适用于私密聊天等需要在同一对用户之间开启多个聊天窗口的场景。
为便于说明,本文按会话 ID 的生成方式,将单聊会话分为两类:
| 概念 | 说明 |
|---|---|
| 单聊单会话 | 传统的单聊会话,会话 ID 即对方的 userID。 |
| 单聊多会话 | 本文介绍的能力,会话 ID 为您自定义的 ID,与对方的 userID 不同。 |
两种单聊会话场景可以在同一个 App 中共存,互不影响。
前提条件
在实现本功能前,请确保:
实现流程
创建会话
单聊多会话不需要提前调用创建接口,直接调用 sendMessage 发送消息即可创建:
- 将
toConversationID传入您自定义的会话 ID,它仅作为会话的唯一标识。 - 将 ZIMMessageSendConfig 的
toPeerUserID传入接收方的userID,它决定消息真正投递给谁。
若 toPeerUserID 为空,SDK 将沿用原有行为,即把 toConversationID 当作对方的 userID 处理,不影响已有的单聊单会话。
// 自定义的会话 ID,需由开发者保证唯一
NSString *conversationID = @"chatID_xxxx";
ZIMTextMessage *textMessage = [[ZIMTextMessage alloc] init];
textMessage.message = @"消息内容";
ZIMMessageSendConfig *config = [[ZIMMessageSendConfig alloc] init];
// 指定消息真正投递到的用户 ID
config.toPeerUserID = @"peerUserID";
ZIMMessageSendNotification *notification = [[ZIMMessageSendNotification alloc] init];
notification.onMessageAttached = ^(ZIMMessage * _Nonnull message) {
// 发送前的回调,开发者可以在此提前展示 UI。
};
[self.zim sendMessage:textMessage toConversationID:conversationID conversationType:ZIMConversationTypePeer config:config notification:notification callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
// 开发者可以通过该回调监听消息是否发送成功。
}];发送成功后,发送方、接收方以及双方各自的其他登录端均会收到 conversationChanged 回调,回调中携带的会话 ID 即为您自定义的会话 ID;此外,接收方还会收到 messageReceived 回调。
后续的单聊会话中,向同一自定义会话 ID 发送消息,消息将进入同一会话;传入新的自定义会话 ID,则会创建新的会话。
- 传入的自定义会话 ID 需要确保唯一,长度不超过 64 字节。
- 请确保自定义会话 ID 不会与真实存在的
userID重复,否则该会话将与对应用户的单聊会话相互混淆,导致消息串流。ZIM 无法识别此类冲突,建议采用与userID明显不同的生成规则(例如带固定前缀的 UUID)。
获取对方的 userID
单聊多会话场景下会话 ID 不再等于对方的 userID,无法直接从会话 ID 推断出聊天对象。
此时可以通过 ZIMConversation 的 relatedID 获取对方的 userID。当会话类型为单聊时,该字段的值即为对方的 userID,两种单聊会话场景都可以使用 relatedID 来获取聊天对象。
单聊单会话场景下 relatedID 的值与会话 ID 一致。
管理会话
单聊多会话场景复用了现有的会话管理能力。设置免打扰、置顶、标记、草稿、消息定时销毁,以及删除会话等操作的用法与普通单聊完全一致,传入自定义的会话 ID 即可。通过 queryConversationListWithConfig 获取会话列表时,单聊多会话也会与其他会话一并返回。
上述接口只能操作已存在的会话。如果目标会话尚未通过发送消息创建,调用将失败并返回错误码 6000603(会话不存在)。
对方的用户信息仍然由 userID 关联,而非会话 ID:
- 当您调用 queryUsersInfo 查询对方的用户信息后,与该
userID关联的所有单聊多会话的conversationName和conversationAvatarUrl都会同步更新。 - 当您调用 updateFriendAlias 修改好友备注后,与该
userID关联的所有单聊多会话同样会同步更新。 - 将对方加入黑名单后,与该
userID关联的所有单聊多会话都会受影响,对方向这些会话发送消息将失败并返回错误码6000284。
注意事项
- 版本兼容:低于 3.2.0 的客户端无法正确处理自定义会话 ID,会将其识别为一个
userID异常的普通单聊会话。因此,请确保使用本功能的用户已升级到 3.2.0 或以上版本,或在业务侧根据客户端版本号决定是否启用本功能。 - 会话数量限制:ZIM 不感知业务层面的会话数量规则,如需限制同一对用户之间可创建的会话数量,请在您的业务后台实现。
- 会话列表长度:服务端保存的会话列表长度存在上限,超出后较早的会话会被移出列表。若某个单聊多会话被移出,您只需使用原有的自定义会话 ID 重新发送消息,即可恢复该会话。
