当前页

为单聊创建多个会话

2026-09-18

功能简介

在 ZIM 中,单聊会话的会话 ID(conversationID)默认为对方的 userID,因此两个用户之间只能存在一个单聊会话。

自 3.2.0 版本起,ZIM 支持为同一对用户创建多个相互独立的单聊会话。支持自定义会话 ID ,不再与对方的 userID 绑定。每个会话拥有独立的消息记录、消息未读数和会话设置,适用于私密聊天等需要在同一对用户之间开启多个聊天窗口的场景。

说明

为便于说明,本文按会话 ID 的生成方式,将单聊会话分为两类:

概念说明
单聊单会话传统的单聊会话,会话 ID 即对方的 userID
单聊多会话本文介绍的能力,会话 ID 为您自定义的 ID,与对方的 userID 不同。

两种单聊会话场景可以在同一个 App 中共存,互不影响。

前提条件

在实现本功能前,请确保:

实现流程

创建会话

单聊多会话不需要提前调用创建接口,直接调用 sendMessage 发送消息即可创建:

  • toConversationID 传入您自定义的会话 ID,它仅作为会话的唯一标识。
  • ZIMMessageSendConfigtoPeerUserID 传入接收方的 userID,它决定消息真正投递给谁。

toPeerUserID 为空,SDK 将沿用原有行为,即把 toConversationID 当作对方的 userID 处理,不影响已有的单聊单会话

// 自定义的会话 ID,需由开发者保证唯一
std::string conversationID = "chatID_xxxx";

zim::ZIMTextMessage text_message;
text_message.message = "消息内容";
zim::ZIMMessage *message = &text_message;

zim::ZIMMessageSendConfig config;
// 指定消息真正投递到的用户 ID
config.toPeerUserID = "peerUserID";

auto notification = std::make_shared<zim::ZIMMessageSendNotification>(
    [=](const std::shared_ptr<zim::ZIMMessage> &message) {});

zim_->sendMessage(message, conversationID, zim::ZIM_CONVERSATION_TYPE_PEER, config, notification,
                  [=](const std::shared_ptr<zim::ZIMMessage> &message,
                      const zim::ZIMError &errorInfo) {});

发送成功后,发送方、接收方以及双方各自的其他登录端均会收到 onConversationChanged 回调,回调中携带的会话 ID 即为您自定义的会话 ID;此外,接收方还会收到 onMessageReceived 回调。

后续的单聊会话中,向同一自定义会话 ID 发送消息,消息将进入同一会话;传入新的自定义会话 ID,则会创建新的会话。

注意
  • 传入的自定义会话 ID 需要确保唯一,长度不超过 64 字节。
  • 请确保自定义会话 ID 不会与真实存在的 userID 重复,否则该会话将与对应用户的单聊会话相互混淆,导致消息串流。ZIM 无法识别此类冲突,建议采用与 userID 明显不同的生成规则(例如带固定前缀的 UUID)。

获取对方的 userID

单聊多会话场景下会话 ID 不再等于对方的 userID,无法直接从会话 ID 推断出聊天对象。

此时可以通过 ZIMConversationrelatedID 获取对方的 userID。当会话类型为单聊时,该字段的值即为对方的 userID,两种单聊会话场景都可以使用 relatedID 来获取聊天对象。

Tips

单聊单会话场景下 relatedID 的值与会话 ID 一致。

管理会话

单聊多会话场景复用了现有的会话管理能力。设置免打扰、置顶、标记、草稿、消息定时销毁,以及删除会话等操作的用法与普通单聊完全一致,传入自定义的会话 ID 即可。通过 queryConversationList 获取会话列表时,单聊多会话也会与其他会话一并返回。

注意

上述接口只能操作已存在的会话。如果目标会话尚未通过发送消息创建,调用将失败并返回错误码 6000603(会话不存在)。

对方的用户信息仍然由 userID 关联,而非会话 ID:

  • 当您调用 queryUsersInfo 查询对方的用户信息后,与该 userID 关联的所有单聊多会话的 conversationNameconversationAvatarUrl 都会同步更新。
  • 当您调用 updateFriendAlias 修改好友备注后,与该 userID 关联的所有单聊多会话同样会同步更新。
  • 将对方加入黑名单后,与该 userID 关联的所有单聊多会话都会受影响,对方向这些会话发送消息将失败并返回错误码 6000284

注意事项

  • 版本兼容:低于 3.2.0 的客户端无法正确处理自定义会话 ID,会将其识别为一个 userID 异常的普通单聊会话。因此,请确保使用本功能的用户已升级到 3.2.0 或以上版本,或在业务侧根据客户端版本号决定是否启用本功能。
  • 会话数量限制:ZIM 不感知业务层面的会话数量规则,如需限制同一对用户之间可创建的会话数量,请在您的业务后台实现。
  • 会话列表长度:服务端保存的会话列表长度存在上限,超出后较早的会话会被移出列表。若某个单聊多会话被移出,您只需使用原有的自定义会话 ID 重新发送消息,即可恢复该会话。
2026-09-18

上一篇

设置会话消息定时销毁

下一篇

功能概述

当前页

返回到顶部