会话列表

大约 4 分钟

会话列表

对于单聊和群组聊天会话,用户发消息时 SDK 会自动创建会话并将会话添加至用户的会话列表。

环信服务器和本地均存储会话,你可以获取会话列表。

前提条件

开始前,请确保满足以下条件:

  • 完成 SDK 初始化,并连接到服务器,详见 快速开始
  • 了解环信即时通讯 IM API 的使用限制,详见 使用限制

技术原理

环信即时通讯 IM 支持从服务器获取会话列表,主要方法如下:

getServerConversations:从服务器分页获取会话列表。

实现方法

从服务器分页获取会话列表

你可以调用 getServerConversations 方法从服务端分页获取会话列表,包含单聊和群组聊天会话,不包含聊天室会话。SDK 按照会话活跃时间(会话的最新一条消息的时间戳)的倒序返回会话列表。

对于每个终端用户,服务器默认存储 100 条会话。超过该限制后,新会话会覆盖旧会话。若会话中的历史消息均过期,会话变成空会话。从服务端拉取会话时不包含空会话。不过,若服务端存在空会话,空会话会占用会话列表名额。如果不希望空会话占用会话列表名额,需要联系商务开通。

提示

  1. 若使用该功能,需在环信控制台开通,并将 SDK 升级至 4.1.7 或以上版本。而且,只有开通该功能,你才能使用置顶会话和会话标记功能。
  2. 登录用户的 ID 大小写混用会导致拉取会话列表时提示会话列表为空,因此建议用户 ID 使用小写字母。
  3. 服务端会话列表的更新存在延时,建议你仅在登录时调用该方法。
  4. 通过 RESTful 接口发送的消息默认不创建或写入会话。若会话中的最新一条消息通过 RESTful 接口发送,获取会话列表时,该会话中的最新一条消息显示为通过非 RESTful 接口发送的最新消息。若要开通 RESTful 接口发送的消息写入会话列表的功能,需在环信即时通讯控制台开通

示例代码如下:

// pageSize: 每页期望获取的会话数量。取值范围为 [1,50],默认为 `20`。
// cursor:开始获取数据的游标位置。若传空字符串(''),SDK 从最新活跃的会话开始获取。
connection.getServerConversations({pageSize:50, cursor: ''}).then((res)=>{
    console.log(res)
})

该方法的返回数据包含 conversationscursor 参数:

  • conversations: 会话列表。conversationsConversationItem[] 类型,ConversationItem 包含如下属性:
属性名称描述
conversationId会话 ID。
conversationType会话类型。
isPinned是否置顶:
- true:置顶;
- false:不置顶。
pinnedTime会话置顶的 UNIX 时间戳,单位为毫秒。未置顶时值为 0
lastMessage最新一条消息概况。
unReadCount未读消息数。
marks会话标记。
  • cursor: 下次查询数据的游标位置。若 SDK 返回的数据条数小于请求中设置的数目,cursor 的值为空字符串(''),表示当前为最后一页数据。否则,SDK 返回具体的游标位置,指定开始获取数据的位置。

接口限制与最佳实践

限制说明推荐做法
最新一条消息与会话未读数延迟刷新或接口调用超过限制频率服务端更新为 异步 行为,收到实时消息后 立即调用本接口 可能获取到 过期数据,即会话中的最新一条消息(lastMessage)和未读数未刷新。1. 初始化会话列表:首次登录后仅调用一次 getServerConversations,将返回结果写入全局状态管理或内存中。
2. 会话更新:收发消息通过回调返回的消息内容更新缓存中的最新一条消息数据以及未读数。
会话信息不完整返回的会话对象 不包含 用户属性(头像、昵称等)以及群组详情(群名称、群公告等)。1. 展示会话列表时先渲染 会话 ID最后一条消息摘要
2. 并行调用 用户属性接口或者 群组详情接口 完善会话信息,并且本地缓存这些信息以避免重复请求。