最近会话（Session） ，即最近联系人列表，它记录了与用户最近有过会话的联系人信息，包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。

最近会话的 API 都挂载在 session 模块中，使用 nim.session 进行访问，具体接口请参见 interface SessionServiceInterface。

生成规则

SDK 会根据漫游消息和离线消息来生成初始会话列表, 在收到消息和发送消息之后，SDK 会更新会话列表。在没有数据库支持时，SDK 内存中会维护一份会话列表。

会话对象

会话对象（type Session）的重要参数如下：

类型	参数名	说明
string	id	会话 id，例如 p2p-cs1、team-113879441
string	scene	会话场景 p2p、team、superTeam
string	to	聊天对象
number	unread	未读数
object	lastMsg	上一条消息
number	ack	自己已读过的最近一条消息的时间
number	msgReceiptTime	聊天对象所读过的最近一条消息的时间

• 己方发送了某条消息 msgFromSelf， 想判定对方是否已读，msgFromSelf.time > session.msgReceiptTime 证明对方未读。
• 对方发送的的消息 msgFromOtherSide, 想判定己方是否已读，msgFromOtherSide.time > session.ack 证明己方未读。

获取本地会话

获取最近会话列表，一般用于首页显示会话列表。

• 通过 SessionServiceInterface-getSession 方法根据 sessionId 从内存中获取会话。
• 通过 getSessions 方法获取内存中的会话列表，支持分页。
• 通过 getAllSessions 获取内存中的所有会话（过滤掉 lastMsg 不存在的会话）。

示例代码如下：

const session = await nim.session.getSession({
  id: 'p2p-cs1'
})

const sessions = await nim.session.getSessions({
  "limit": 10,
  "desc": true
})

const sessions = await nim.session.getAllSessions(
)

删除会话

删除最近会话列表，可以删除指定的会话，也可以删除全部会话。

• 通过 deleteSession 方法删除指定的会话，同时可选发送协议，让服务器清除此会话的漫游消息。在下一次登录时，如果没有新的消息下发，则不会再次生成会话。
• 通过 deleteAllSessionsFromLocal 方法删除所有本地缓存的会话，如果会话内存在消息，则在下一次登录时继续生成会话。

若开发者使用了置顶会话功能，那么推荐您在删除会话时进行判定（是否存在云端置顶会话），根据自身需求决定是否取消置顶会话，具体请参见示例代码。

示例代码如下：

// 假设已经得到一个 `p2p-cs1` 的 session，并且其中存在着若干条消息
// first time init
const nim = new NIMSDK(options)
await nim.connect()
await nim.session.deleteAllSessionsFromLocal()
var session = nim.session.getSession({ id: 'p2p-cs1' })
console.log(session) // undefined
await nim.destroy()
nim = null

// second time init
const nim1 = new NIMSDK(options)
await nim1.connect()
var session = nim1.session.getSession({ id: 'p2p-cs1' })
console.log(session) // { sessionId: 'p2p-cs1', ... }
// 若存在云端置顶会话，则去移除会话的置顶。
if (session.stickTopInfo && session.stickTopInfo.isStickOnTop) {
  await nim1.session.deleteStickTopSession({
    "id": "p2p-cjhz1"
  })
}
await nim1.session.deleteSession({
  // sessionId
  "id": "p2p-cs1",
  // true: delete roaming msg in session。
  "isSyncToServer": true
})
var session = nim1.session.getSession({ id: 'p2p-cs1' })
console.log(session) // undefined
await nim1.destroy()
nim1 = null

// third time init
const nim2 = new NIMSDK(options)
await nim2.connect()
var session = nim1.session.getSession({ id: 'p2p-cs1' })
console.log(session) // undefined

重置会话未读数

重置当前会话，SDK 会自动管理消息的未读数。

• 通过 resetSessionUnreadCount 方法清空某个 session 的未读数计数。
• 通过 resetAllSessionsUnreadCount 方法清空所有 session 的未读数计数。

示例代码如下：

await nim.session.resetSessionUnreadCount({
  "id": "p2p-cs2",
})

var session = nim1.session.getSession({ id: 'p2p-cs2' })
console.log(session.unread) // 0

// or you can reset all session unread count
// await nim.session.resetAllSessionsUnreadCount()

置顶会话

会话置顶功能需要单独开通，您可通过云信官网提供的联系方式咨询商务经理开通。

SDK 支持置顶/取消置顶/更新置顶最近会话。将会话设置为云端置顶后，IM 服务器将会在云端记录中置顶会话，包括会话id，置顶的扩展字段等信息。

• 通过 addStickTopSession 方法添加云端置顶的会话。设置置顶会话后，会显示 session 定义中的 stickTopInfo 属性。
• 通过 deleteStickTopSession 方法取消云端置顶的会话。
• 通过 updateStickTopSession 方法更新云端置顶的会话，目前仅能更新会话的扩展字段。

示例代码如下：

let session = await nim.session.addStickTopSession({
  "id": "p2p-cjhz1",
  "ext": "extensions"
})

console.log(session)
{
//     "id": "p2p-cjhz1",
//     "scene": "p2p",
//     "to": "cjhz1",
//     "lastMsg": { ... },
//     "updateTime": 1658739496811,
//     "unread": 0,
//     "unreadMsgs": [],
//     "ack": 1656587535333,
//     "stickTopInfo": {
//         "id": "p2p-cjhz1",
//         "ext": "extensions",
//         "createTime": 1659063314105,
//         "updateTime": 1659063314105,
//         "isStickOnTop": true
//     }
// }

session = await nim.session.updateStickTopSession({
  "id": "p2p-cjhz1",
  "ext": "extensions_1"
})

session = await nim.session.deleteStickTopSession({
  "id": "p2p-cjhz1"
})

对比 IM1

IM Web Elite 与 IM1 对比，废弃了 setCurrentSession 功能。

IM1 版本的 setCurrentSession 的效果是：会将此会话未读数置为 0，并且实例能收到 updateSession 事件代表会话被更新，之后此会话在收到消息时不再更新未读数。

为了更灵活的处理已读未读和未读计数逻辑，推荐您结合 resetSessionUnreadCount 和 sendMsgReceipt 使用。

1. UI 上进入会话时，首先调用 resetSessionUnreadCount + sendMsgReceipt 清除一遍会话数量和标记消息已读。
2. 记录当前激活的会话id。每当收到 updateSession 事件，判断后调用 resetSessionUnreadCount 清除此会话未读数。