获取远端会话
会话列表支持超级群
自 5.20.0 版本开始,SDK 支持在获取会话列表中返回超级群会话信息,以便于开发者根据业务需求对单聊、群聊、超级群会话列表进行混合排序展示;该功能需提交工单开启。
功能开启后,SDK 在连接成功后,从服务器拉取所有会话数据至本地内存中进行维护,并在开发者调用接口时,从内存中按查询条件返回相关会话数据。
- 单聊、群聊会话同步完成后,SDK 将通知
Events.CONVERSATIONS_SYNCED
事件; 超级群会话同步完成后,SDK 将通知Events.ULTRA_GROUP_ENABLE
事件;建议在接收到以上两个事件后再拉取获取会话列表进行渲染,否则数据结果可能存在丢失、排序异常等问题。 - Electron 平台自 5.28.0 版本开始支持超级群业务。
- 会话列表结果中仅包含超级群的默认频道会话数据,不包含子频道会话。
获取会话列表
SDK 从 5.28.0 版本开始新增 getConversationListByTimestamp 接口,用于替换原 getConversationList 接口,以解决原接口的二义性问题。
- 非 Electron 平台:
channelId
参数无效,始终按时间戳获取会话列表。 - Electron 平台:
- 当
channelId
为字符串时,其行为与非 Electron 平台保持一致,按时间戳返回数据。 - 当
channelId
为undefined
时,该接口返回本地数据库存储的全量数据。
- 当
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
params | IGetConversationListByTimestampParams | 是 | 查询参数 |
IGetConversationListByTimestampParams 结构属性说明
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
startTime | number | 是 | 获取会话的起始时间,需要精确到毫秒,0 表示当前时间 |
count | number | 是 | 获取数量 |
order | number | 否 | 查询方向,同时影响结果排序,该参数对 Electron 平台无效 0 - 从 startTime 开始向前查询,数据按时间降序排序 1 - 从 startTime 开始向后查询,数据按时间升序排序 |
topPriority | boolean | 否 | 是否将置顶会话排序优先 |
conversationTypes | Array<ConversationType> | 否 | 会话类型,值为空或长度为 0 时,获取全部会话类型。该参数仅 Electron 平台有效 |
示例代码
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
接口以获取远端会话列表数据,这样可能带来以下问题:
- 可能导致接口报错或请求失败。
- 返回的会话数据可能并非最新。
- 多次拉取远端数据会增加网络负载,降低应用性能。
服务端按照会话最后一条消息的时间进行排序:
- 获取最新会话列表:设置
order = 0
,startTime = 0
,表示以当前时间为边界,查询早于当前时间的会话,返回最新列表。 - 获取服务端最早会话:设置
order = 1
,startTime = 0
,表示从服务端最早一条开始获取指定数量会话,最多返回 1000 条。 - 分页查询:翻页查询时,将上次返回的最后一条 IAReceivedConversation 的
latestMessage.sendTime
作为新的startTime
,按需继续请求。
获取全部会话
当您需要一次性获取所有会话数据时,可以使用 getAllConversationList 接口。该接口支持多平台,用于替换 electronExtension.getAllConversationList
接口。
- 获取全部会话接口从 5.28.0 版本开始支持。
- 查询全部会话会产生较大的数据查询压力,建议谨慎使用。推荐使用 getConversationListByTimestamp 接口进行分页查询。
示例代码
RongIMLib
.getAllConversationList()
.then(res => {
if (res.isOk) {
console.log('获取会话列表成功:', res.data);
} else {
console.log('获取会话列表失败:', res.code);
}
});
获取指定会话
通过该方法获取的会话可能并不存在于当前的会话列表中,此处只作为功能性封装语法糖。
调用 getConversation 方法,获取指定会话 IAReceivedConversation。
接口
RongIMLib.getConversation(conversation)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
conversation | IConversationOption | 是 | 目标会话 |
示例代码
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 获取置顶会话列表。
接口
RongIMLib.getTopConversationList(conversationTypes, channelId)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
conversationTypes | ConversationType[] | 是 | 会话类型数组,默认包含所有类型 |
示例代码
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 获取含有未读消息的会话列表。
接口
RongIMLib.getUnreadConversationList(conversationTypes)
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
conversationTypes | ConversationType[] | 是 | 会话类型数组 |
示例代码
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 平台。
接口
RongIMLib.getBlockedConversationList()
代码示例
RongIMLib.getBlockedConversationList().then(res => {
if (res.code === 0) {
console.log(res.code, res.data)
} else {
console.log(res.code, res.msg)
}
})