最近会话 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

生成规则

SDK 会根据漫游消息和离线消息来生成初始会话列表，在收到消息和发送消息之后 SDK 会更新会话列。

初始化参数

这里的参数并不是所有的初始化参数，请参考初始化 SDK，以及其它章节的初始化参数：

示例代码

JavaScriptvar nim = NIM.getInstance({
    onsessions: onSessions,
    onupdatesession: onUpdateSession
});
function onSessions(sessions) {
    console.log('收到会话列表', sessions);
    data.sessions = nim.mergeSessions(data.sessions, sessions);
    updateSessionsUI();
}
function onUpdateSession(session) {
    console.log('会话更新了', session);
    data.sessions = nim.mergeSessions(data.sessions, session);
    updateSessionsUI();
}
function updateSessionsUI() {
    // 刷新界面
}

参数解释

syncSessionUnread，是否同步会话的未读数，默认不同步。
- 如果选择同步。
  - 那么在一个端读过的会话在其它端也会被标记为已读。
  - 在调用设置当前会话的时候 SDK 会自动同步一次未读数，此后如果收到当前会话的消息，需要手动调用重置会话未读数来同步未读数。
onsessions，同步最近会话列表回调，会传入会话列表，按时间正序排列，即最近聊过天的放在列表的最后面。
- 此回调是增量回调，可以调用 nim.mergeSessions 来合并数据。
onupdatesession，更新会话的回调，会传入会话对象，以下情况会收到此回调。
- 收到消息。
- 发送消息
- 设置当前会话
- 重置会话未读数

会话对象

会话对象有以下字段:

id：会话 ID。
scene：场景。
to：聊天对象，账号或群 ID。
updateTime：会话更新的时间。
unread：未读数。
lastMsg：此会话的最后一条消息。
msgReceiptTime：消息已读回执时间戳，如果有此字段，说明此时间戳之前的所有消息对方均已读。
- 目前仅对 'p2p' 会话起作用。
- 此字段不一定有，只有对方发送过已读回执之后才会有。
- 调用接口发送消息已读回执来发送消息已读回执。
- 调用接口查询消息是否被对方读过了来查询消息是否被对方读过了。
localCustom：本地自定义扩展字段。
- 在支持数据库时可以调用更新本地会话来更新此字段，此字段只会被更新到本地数据库，不会被更新到服务器上。

未读数

SDK 会自动管理会话的未读数，会话对象的 unread 的值为会话的未读数，如果开发者发现会话的未读数大于收到的离线消息数，那么需要从本地拉取未读取的消息。

会话未读数的初始化在不同的配置环境下，会有不同的计算规则：

是否开启同步会话未读数

开启同步会话未读数：syncSessionUnread = true。
- 此时会话未读数通过服务器下推的 Ack 或本地存储的 Ack 时间戳，与本地数据库中对应会话的本地历史记录做比较，晚于该 Ack 且不是自己发的消息的数量，为未读数。
- 参考会话初始化参数。
未开启同步会话未读数：syncSessionUnread = false。
- 此时会话未读数通过从本地数据库上次所记录的未读数中取得，如果有离线消息且消息属性标记为 isUnreadable，则会在原来的未读数上增加计数。

是否开启自动标记消息已读

不开启自动标记消息已读：autoMarkRead = false

此时服务器下推的所有离线消息算未读，漫游消息算已读。
开启自动标记消息已读：autoMarkRead = true
- 此时每次收到离线消息，均会告知服务器该消息已读，下一次登录，服务器就不会下推离线消息，而将这些消息标记为漫游消息。没有离线消息，未读数在表现上均为 0。
- 参考标记消息为已收到。

设置当前会话

如果是已经存在的会话记录，会将此会话未读数置为 0，并触发 onupdatesession 回调。
之后此会话在收到消息之后不会更新未读数。

JavaScriptnim.setCurrSession('sessionId')

取消设置当前会话

取消设置当前会话后，会话在收到消息之后会持续更新未读数。

JavaScriptnim.resetCurrSession();

重置会话未读数

如果是已经存在的会话记录，会将此会话未读数置为 0，那么会收到 onupdatesession 回调。
之后此会话在收到消息之后依然会更新未读数。

JavaScriptnim.resetSessionUnread('sessionId')

重置所有会话未读数(内存中的)

如果是内存中已经存在的会话记录，会将该内存中的所有会话记录的未读数均清零，那么会多次收到 onupdatesession 回调。
之后此会话在收到消息之后依然会更新未读数。

JavaScriptnim.resetAllSessionUnread()

获取本地会话列表

通过 lastSessionId 获取本地会话

仅查询内存中的会话列表（提前同步）
lastSessionId 为上次查询的最后一条会话的 id，第一次不填。
limit 为本次查询的会话数量限制，最多 100 条，默认 100 条。
默认从最近的会话开始往前查找本地会话，可以传参数 reverse=true 来从第一条会话开始往后查找本地会话。

JavaScriptnim.getLocalSessions({
    lastSessionId: lastSessionId,
    limit: 100,
    done: getLocalSessionsDone
});
function getLocalSessionsDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('获取本地会话列表' + (!error?'成功':'失败'));
    if (!error) {
        onSessions(obj.sessions);
    }
}

通过 sessionId 获取本地会话

优先在内存中的会话列表（提前同步）查询，若不存在，在支持数据库的情况下，再从本地数据库中获取，有则返回会话对象，无则返回 null。
sessionId 为需要查询的会话的 sessionId。

JavaScriptnim.getLocalSession({
    sessionId: sessionId,
    done: getLocalSessionDone
});
function getLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('获取本地会话操作' + (!error ? '完成' : '失败'), error, obj)
}

指定 lastMsg 类型获取本地会话列表

在数据库中查询指定类型的会话列表。
返回按时间逆序排列的、包含指定类型消息的会话(通过参数 exclude 传入要排除的消息类型，剩余的就是指定类型），返回会话的 lastMsg 是该会话中最近的、类型符合条件的消息，最多 100 条。
具体参数和使用参考 API 文档。

插入一条本地会话记录

您可以插入一条本地会话记录，数据保存在内存中，在支持数据库时，SDK 也会将此会话存储于本地数据库。
SDK 会设置一个比当前所有会话更新时间大的一个时间为此会话的更新时间，或者您可以传入参数 updateTime 来指定更新时间。
在回调里面，您需要保存生成的会话。

JavaScriptnim.insertLocalSession({
    scene: 'p2p',
    to: 'account',
    done: insertLocalSessionDone
});
function insertLocalSessionDone(error, obj) {
    console.log('插入本地会话记录' + (!error?'成功':'失败'), error, obj);
    if (!error) {
        onSessions(obj.session);
    }
}

更新本地会话

在内存（提前同步）和数据库中更新 id 对应的本地会话。
若不支持数据库，则更新内存中的指定会话。
如果对应的会话不存在，算成功，返回 null
这些字段会被更新到本地数据库，并完成同步。
目前只允许更新 localCustom。

通过入参 needNotify 来控制是否触发更新会话的回调。若 needNotify 为 true，触发 onUpdateSessions 和 onUpdateSession 的回调。needNotify 为 false 则不触发。默认为 true。

JavaScriptnim.updateLocalSession({
    id: 'p2p-account',
    localCustom: '{"key","value"}',
    done: updateLocalSessionDone
});
function updateLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('更新本地会话' + (!error?'成功':'失败'));
}

删除本地会话

删除内存（提前同步）和数据库中的指定会话。
若不支持数据库，则删除内存中的指定会话。
如果对应的会话不存在，算成功。

参数 ID 为会话 ID 或 ID 数组。

JavaScriptnim.deleteLocalSession({
    id: 'p2p-account',
    done: deleteLocalSessionDone
});
function deleteLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('删除本地会话' + (!error?'成功':'失败'));
}

删除服务器上的会话

如果仅需要删除漫游消息，可调用 deleteLocalSession 方法，设置入参 isDeleteRoaming 为 true，即可删除漫游消息。

如果需要删除漫游消息，以及历史消息，可调用 clearServerHistoryMsgsWithSync 方法进行删除。

JavaScript//仅需要删除漫游消息。
nim.deleteLocalSession({
    id: 'p2p-account',
    isDeleteRoaming: true,
    done: deleteLocalSessionDone
});
function deleteLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('删除漫游消息' + (!error?'成功':'失败'));
}
//删除漫游消息和历史消息。
nim.clearServerHistoryMsgsWithSync({
    //p2p:点对点; team:群; superTeam:超大群。
    scene: 'p2p',
    //为对方账号或群 ID
    to: 'account',
    done: clearServerHistoryMsgsWithSyncDone
});
function clearServerHistoryMsgsWithSyncDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('删除漫游消息和历史消息' + (!error?'成功':'失败'));
}

服务端会话列表服务

v7.0.0 以上版本支持服务端会话列表服务，这是一种新的会话列表服务，跟 SDK 的 最近会话 是两种不同的，完全隔离的。

最近会话 是由 SDK 生成和维护，而服务端会话列表服务由服务器维护，记录的会话数量较多，超过了 100 条的限制，但没有 unread，msgReceiptTime 等属性。

SDK 提供了以下 API，供开发者获取、更改、删除服务端会话。

在多端登录时，若一端更新服务器会话的扩展字段，SDK 会通过 onSyncUpdateServerSession 回调函数通知开发者，可以在 SDK 初始化时传入该监听函数。

常见问题

为什么重新连接后获取到的会话数减少？

此文档是否对你有帮助？

有帮助

去反馈

生成规则
初始化参数
会话对象
未读数
是否开启同步会话未读数
是否开启自动标记消息已读
设置当前会话
取消设置当前会话
重置会话未读数
重置所有会话未读数(内存中的)
获取本地会话列表
通过 lastSessionId 获取本地会话
通过 sessionId 获取本地会话
指定 lastMsg 类型获取本地会话列表
插入一条本地会话记录
更新本地会话
删除本地会话
删除服务器上的会话
服务端会话列表服务
常见问题