跳到主要内容
版本：5.X

获取会话

提示
  • Web 端不具备持久化的数据存储能力，无法在本地持久化存储历史消息记录与会话列表，因此需要从融云服务端获取数据。从远端获取单群聊历史消息要求您已在控制台 IM 服务的服务购买页面为当前使用的 App Key 开启单群聊消息云端存储服务。IM 旗舰版或IM 尊享版可开通该服务。具体功能与费用以融云官方价格说明页面及计费说明文档为准。
  • 获取远端会话必须在调用 RongIMLib.connect() 并且成功建立连接之后执行。
  • 服务器会话列表存储上限为 1000 条会话，会话存储有效期与单群聊消息云端存储的有效期一致，默认为 6 个月。

会话列表支持超级群​

自 5.20.0 版本开始，SDK 支持在获取会话列表中返回超级群会话信息，以便于开发者根据业务需求对单聊、群聊、超级群会话列表进行混合排序展示；该功能需提交工单开启。

功能开启后，SDK 在连接成功后，从服务器拉取所有会话数据至本地内存中进行维护，并在开发者调用接口时，从内存中按查询条件返回相关会话数据。

注意
  • 单聊、群聊会话同步完成后，SDK 将通知 Events.CONVERSATIONS_SYNCED 事件； 超级群会话同步完成后，SDK 将通知 Events.ULTRA_GROUP_ENABLE 事件；建议在接收到以上两个事件后再拉取获取会话列表进行渲染，否则数据结果可能存在丢失、排序异常等问题。
  • Electron 平台自 5.28.0 版本开始支持超级群业务。
  • 会话列表结果中仅包含超级群的默认频道会话数据，不包含子频道会话。

分页获取会话列表​

SDK 从 5.32.0 版本开始新增 createConversationListLoader 接口，用于在未来逐步统一和归拢所有的会话列表获取接口，以简化开发者集成流程。该接口在调用成功时，返回一个 ConversationListLoader 实例，通过调用该实例的 load() 方法分页加载会话列表数据。

警告

目前该接口暂不支持 Electron 平台。

接口​

JavaScript
RongIMLib.createConversationListLoader(options)

参数说明​

参数类型必填说明
optionsIConversationListLoaderOptions是查询条件参数

示例代码​

JavaScript
// ...

// 定义查询条件
const options = {
  conversationTypes: [ConversationType.PRIVATE, ConversationType.GROUP],
  // 标签过滤器，可选参数；不传则不进行标签过滤
  tagFilter: {
    tagIds: [],
    topPriority: false, // 是否按标签内置顶优先返回，仅当 tagIds 列表有值时有效
  },
  // 查询顺序
  // 0 为降序（默认），从最新会话开始查询
  // 1 为升序，从最早的会话开始查询
  order: 0,
};

const { isOk, code, data: loader } = await RongIMLib.createConversationListLoader(options);
if (!isOk) {
  console.log('创建 Loader 实例失败', code);
  return;
}

// 开发者需要持续持有 loader 引用，以便在需要时加载更多会话

// 指定加载数量，有效值 [1, 100]
const res = await loader.load(10);
if (res.isOk) {
  console.log('会话列表获取成功：', res.data);
} else {
  console.log('会话列表获取失败：', res.code);
}
// ...

获取会话列表​

SDK 从 5.28.0 版本开始新增 getConversationListByTimestamp 接口，用于替换原 getConversationList 接口，以解决原接口的二义性问题。

原 getConversationList 接口二义性问题说明：
  1. 非 Electron 平台：channelId 参数无效，始终按时间戳获取会话列表。
  2. Electron 平台：
    • 当 channelId 为字符串时，其行为与非 Electron 平台保持一致，按时间戳返回数据。
    • 当 channelId 为 undefined 时，该接口返回本地数据库存储的全量数据。

参数说明​

参数类型必填说明
paramsIGetConversationListByTimestampParams是查询参数

IGetConversationListByTimestampParams 结构属性说明

属性类型必填说明
startTimenumber是获取会话的起始时间，需要精确到毫秒，0 表示当前时间
countnumber是获取数量
ordernumber否查询方向，同时影响结果排序，该参数对 Electron 平台无效
0 - 从 startTime 开始向前查询，数据按时间降序排序
1 - 从 startTime 开始向后查询，数据按时间升序排序
topPriorityboolean否是否将置顶会话排序优先
conversationTypesArray<ConversationType>否会话类型，值为空或长度为 0 时，获取全部会话类型。该参数仅 Electron 平台有效

示例代码​

JavaScript
const params = {
  startTime: 0,
  count: 10,
};

RongIMLib
  .getConversationListByTimestamp(params)
  .then(res => {
    if (res.isOk) {
      console.log('获取成功：', res.data);
    } else {
      console.log('获取失败：', res.code);
    }
  });
接口使用建议

在 Web 端调用该接口时，获取的数据为远端存储的会话数据。为提升性能并减少接口调用风险，建议按以下方式处理：

首次获取数据 业务层在拉取离线消息完成后，可主动调用该接口一次，将返回的会话数据赋值给业务层的渲染数据，以确保初始状态的完整性。

数据更新方式 后续会话数据的更新将通过 会话变更通知事件监听 返回。业务层可根据事件返回的数据，与本地渲染数据进行合并更新，而无需频繁调用 getConversationListByTimestamp 接口。

避免频繁调用接口 请勿在每次收发消息时主动调用 getConversationListByTimestamp 接口以获取远端会话列表数据，这样可能带来以下问题：

  1. 可能导致接口报错或请求失败。
  2. 返回的会话数据可能并非最新。
  3. 多次拉取远端数据会增加网络负载，降低应用性能。
服务端排序规则说明

服务端按照会话最后一条消息的时间进行排序：

  • 获取最新会话列表：设置 order = 0，startTime = 0，表示以当前时间为边界，查询早于当前时间的会话，返回最新列表。
  • 获取服务端最早会话：设置 order = 1，startTime = 0，表示从服务端最早一条开始获取指定数量会话，最多返回 1000 条。
  • 分页查询：翻页查询时，将上次返回的最后一条 IAReceivedConversation 的 latestMessage.sendTime 作为新的 startTime，按需继续请求。

获取全部会话​

当您需要一次性获取所有会话数据时，可以使用 getAllConversationList 接口。该接口支持多平台，用于替换 electronExtension.getAllConversationList 接口。

注意
  • 获取全部会话接口从 5.28.0 版本开始支持。
  • 查询全部会话会产生较大的数据查询压力，建议谨慎使用。推荐使用 getConversationListByTimestamp 接口进行分页查询。

示例代码​

JavaScript
RongIMLib
  .getAllConversationList()
  .then(res => {
    if (res.isOk) {
      console.log('获取会话列表成功：', res.data);
    } else {
      console.log('获取会话列表失败：', res.code);
    }
  });

获取指定会话​

提示

通过该方法获取的会话可能并不存在于当前的会话列表中，此处只作为功能性封装语法糖。

调用 getConversation 方法，获取指定会话 IAReceivedConversation。

接口​

JavaScript
RongIMLib.getConversation(conversation)

参数说明​

参数类型必填说明
conversationIConversationOption是目标会话

示例代码​

JavaScript
const conversationType = RongIMLib.ConversationType.PRIVATE;
const targetId = '接收方的 userId';

RongIMLib.getConversation({
    conversationType,
    targetId,
}).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

获取置顶会话列表​

提示
  • 从 SDK 5.6.0 开始支持该接口。

调用 getTopConversationList 获取置顶会话列表。

接口​

JavaScript
RongIMLib.getTopConversationList(conversationTypes, channelId)

参数说明​

参数类型必填说明
conversationTypesConversationType[]是会话类型数组，默认包含所有类型

示例代码​

JavaScript
const conversationTypes = [RongIMLib.ConversationType.PRIVATE, RongIMLib.ConversationType.GROUP, RongIMLib.ConversationType.SYSTEM];

RongIMLib.getTopConversationList(conversationTypes).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

获取未读会话列表​

提示
  • 从 SDK 5.7.0 开始支持该接口。

调用 getUnreadConversationList 获取含有未读消息的会话列表。

接口​

JavaScript
RongIMLib.getUnreadConversationList(conversationTypes)

参数说明​

参数类型必填说明
conversationTypesConversationType[]是会话类型数组

示例代码​

JavaScript
const conversationTypes = [RongIMLib.ConversationType.PRIVATE, RongIMLib.ConversationType.GROUP, RongIMLib.ConversationType.SYSTEM];

RongIMLib.getUnreadConversationList(conversationTypes).then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

获取免打扰会话列表​

调用 getBlockedConversationList 获取已配置免打扰的会话列表。

提示
  • 从 5.28.0 版本开始，该接口支持 Electron 平台。

接口​

JavaScript
RongIMLib.getBlockedConversationList()

代码示例​

JavaScript
RongIMLib.getBlockedConversationList().then(res => {
  if (res.code === 0) {
    console.log(res.code, res.data)
  } else {
    console.log(res.code, res.msg)
  }
})

筛选包含机器人的会话列表​

提示
  • 需升级 SDK 版本至 5.32.0 及以上。
  • 目前仅支持获取单聊、系统会话类型。

通过调用 getConversationsIncludingRobots 接口，可获取所有包含机器人的会话列表。

接口​

JavaScript
RongIMLib.getConversationsIncludingRobots(options)

参数​

options 参数类型为 IGetConversationsIncludingRobotsOption。

属性名类型是否必填描述
options.conversationTypesConversationType是会话类型数组，用于筛选会话类型，目前仅支持：
单聊（ConversationType.PRIVATE）
系统会话（ConversationType.SYSTEM）
options.countnumber是获取数量，有效值为 [1, 100]
options.timestampnumber是时间戳，获取最新会话时传 0
options.topPriorityboolean否是否置顶会话优先，该参数仅支持 Electron 平台

示例代码​

JavaScript
const options = {
  conversationTypes: [ConversationType.PRIVATE, ConversationType.SYSTEM],
  timestamp: 0,
  count: 10,
};
RongIMLib.getConversationsIncludingRobots(options).then(res => {
  if (res.isOk) {
    console.log('获取会话列表完成：', res.data);
  } else {
    console.log('获取会话列表失败：', res.code);
  }
})