历史记录

本地记录

提供了比较完善的消息记录管理功能,开发者可本地查阅、在线查阅、删除和清空聊天记录,还可以写入消息记录,导入/导出历史消息(仅能导入当前用户的记录)。此外,还要注意:本地消息历史操作(如删除)及状态变化(如发送失败或成功)会与会话列表里的消息状态自动同步,App 上层需要根据监听会话列表通知回调进行相应通知事件的处理。

全局消息状态变更通知

注册全局的消息状态变更通知(目前只支持已读状态的通知)。当收到对方的消息已读回执时,会通过此注册的回调通知给调用者。

public static void RegMsglogStatusChangedCb(MsglogStatusChangedDelegate cb);
//注册全局的消息状态变更通知
NIM.Messagelog.MessagelogAPI.RegMsglogStatusChangedCb((code,result)=>
{
    //result为json字符串,示例:[{"talk_id":"test1","msg_timetag":"1520500638234","status":2}]
    ...
});

查询消息历史

SDK 提供了一个根据锚点查询本地消息历史记录的接口,结果使用 time 作为排序字段(按时间逆序起查,逆序排列)。

public static void QueryMsglogLocally(string accountId, NIMSessionType sType, int limit, long msgAnchorTimetag, QueryMsglogResultDelegate action)
参数 说明
accountId 会话id,对方的account id或者群组tid
sType 会话类型
limit 一次查询数量,建议20
msgAnchorTimetag 上次查询最后一条消息的时间戳(按时间逆序起查,即最小的时间戳)
action 查询结果回调通知
NIM.Messagelog.MessagelogAPI.QueryMsglogLocally("session_id", NIM.Session.NIMSessionType.kNIMSessionTypeP2P, 20, 0, (code, accountId, sType, result) =>
{
    if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
});

包含起止时间的本地消息历史查询

该接口使用方法与查询历史消息类似, 根据MsgAnchorTimttag时间查询更早或更晚的消息,返回 limit 条记录,如果小于 limit 条,返回实际条数。目前仅是查询消息历史基础上支持Direction,暂时不支持EndTimetagReverse

public static void QueryMsglogLocally(QueryMsglogParams args, QueryMsglogResultDelegate action);

QueryMsglogParams 重要参数说明

类型 参数 说明
string AccountId 会话id,对方的account id或者群组tid
NIMSessionType SessionType 会话类型
int CountLimit 查询条数上限 必须大于0
long MsgAnchorTimttag 查询时间锚点时间戳(毫秒)
long EndTimetag 查询时间截止点时间戳(毫秒),暂不支持
MsglogSearchDirection Direction 查询更早或更晚的消息
bool Reverse true:反向查询(按时间正序起查,正序排列),false:按时间逆序起查,逆序排列(建议默认为false),暂不支持

MsglogSearchDirection 属性说明:

枚举 说明
kForward 0 查询比锚点时间更早的消息
kBackward 1 查询比锚点时间更晚的消息
// 以P2P类型为例,testAccount为测试帐号
QueryMsglogParams param = new QueryMsglogParams{
    AccountId="testAccount为测试帐号",
    SessionType=kNIMSessionTypeP2P,
    CountLimit = 20,
    MsgAnchorTimttag = 1519977874123,//13位时间戳毫秒
    EndTimetag = 1519978139567//13位时间戳毫秒
    Direction = MsglogSearchDirection.kBackward
};
NIM.Messagelog.MessagelogAPI.QueryMsglogLocally(param, (code, accountId, sType, result) =>
{
    if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
});

根据消息 uuid 查询消息

public static void QuerylogById(string clientMsgId, QueryLogByMsgIdResultDelegate action);
参数 说明
clientMsgId 所查询的消息id
action 查询结果回调通知
string clientMsgId="msg_id";//以实际的消息id为准
MessagelogAPI.QuerylogById(clientMsgId, (code, msdId, msg)=>
{
    ...
});

根据指定条件查询本地消息

根据指定条件查询本地消息,使用此接口可以完成全局搜索等功能,具体请参阅开发手册。暂时仅支持单个id的查询,即ids只能添加一个,不支持多个uid。searchContent参数不能为空。

 public static void QueryMsglogByCustomCondition(NIMMsgLogQueryRange range, string[] ids, int limit,
            long sTimetag, long eTimetag, string endMsgId, bool reverse,
            NIMMessageType msgType, string searchContent, QueryMsglogResultDelegate action);
参数 说明
range 消息历史的检索范围
ids 会话id,对方的account id的集合或者群组tid的集合,目前仅支持单个id的查询
limit 搜索结果的条数限制
sTimetag 起始时间戳,单位:毫秒
eTimetag 结束时间戳,单位:毫秒
endMsgId 结束查询的最后一条消息的client_msg_id(不包含在查询结果中)(暂不启用)
reverse true:反向查询(按时间正序起查,正序排列),false:按时间逆序起查,逆序排列(建议默认为false)
msgType 检索的消息类型(目前只支持kNIMMessageTypeText、kNIMMessageTypeImage和kNIMMessageTypeFile这三种类型消息)
searchContent 检索文本(目前只支持kNIMMessageTypeText和kNIMMessageTypeFile这两种类型消息的文本关键字检索,即支持文字消息和文件名的检索。如果合并检索,需使用未知类型消息kNIMMessageTypeUnknown
action 查询结果回调

NIMMsgLogQueryRange枚举类型

枚举 说明
kNIMMsgLogQueryRangeP2P 0 指定的个人(点对点会话)(注意:暂不支持指定多个人的检索!)
kNIMMsgLogQueryRangeTeam 1 指定的群组(注意:暂不支持指定多个群组的检索!)
kNIMMsgLogQueryRangeAll 100 全部
kNIMMsgLogQueryRangeAllP2P 101 所有个人会话
kNIMMsgLogQueryRangeAllTeam 102 所有群组
kNIMMsgLogQueryRangeUnknown 200 不支持查询
//以P2P消息为例
string[] ids = new string[]();
ids.add("testAccount");
long sTimetag = 1519977874123;//13位时间戳毫秒
long eTimetag = 1519978139567;13位时间戳毫秒,需要比sTimetag更晚,即eTimetag > sTimetag
NIM.Messagelog.QueryMsglogByCustomCondition(NIMMsgLogQueryRange.kNIMMsgLogQueryRangeP2P, ids, 20,
            sTimetag, eTimetag, "", false, NIMMessageType.kNIMMessageTypeText, "111", (code, accountId, sType, result) =>
{
    if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
})

插入本地消息

保存消息到本地数据库,如果已存在这条消息,则更新,但不发送到服务器端。需要保证整条消息内容是符合消息收发的规范。

public static void WriteMsglog(string uid, bool need_update_session, NIMIMMessage msg, OperateSingleLogResultDelegate action);
参数 说明
uid 会话id,对方的account id或者群组tid
need_update_session 是否更新会话列表(一般最新一条消息会有更新的需求)
msg 消息体,详见NIMIMMessage
action 操作结果的回调函数
// 创建一条文本消息,以对方账号testAccount为例
NIMTextMessage msg = new NIMTextMessage();
msg.ClientMsgID="uuid";//该条消息唯一id
msg.TalkID="testAccount";对方账号
msg.ReceiverID="testAccount";对方账号
msg.TimeStamp=1519977874123;//13位时间戳毫秒
msg.MsgLogStatus=NIMMsgLogStatus.kNIMMsgLogStatusDraft;//可设置其他消息状态
msg.TextContent="111";
...
// 保存消息到本地数据库,但不发送到服务器
NIM.Messagelog.MessagelogAPI.WriteMsglog("testAccount",true, msg, (code, msgId)=>
{
    ...
});

删除历史消息

可以删除指定msgid的消息,也可以批量删除消息。

1. 删除指定的一条消息

通过指定对方account或者群id,msgId来删除历史消息

public static void DeleteSpecifiedMsglog(string sid, NIMSessionType sType, string msgId, OperateSingleLogResultDelegate action);
参数 说明
sid 对方account或者群id
sType 当前会话的类型,指定枚举类型NIMSessionType
msgId 指定要删除的消息唯一id
action 操作结果回调通知
//以p2p消息为例,测试账号testAccount
NIM.Messagelog.MessagelogAPI.DeleteSpecifiedMsglog("testAccout",NIMSessionType.kNIMSessionTypeP2P,"client_msgid",(code,msgId)=>
{
    ...
});

2. 删除指定会话类型的所有消息

通知指定sType批量删除数据库中的历史记录,只操作本地数据库,不同步服务器。

public static void DeleteMsglogsBySessionType(NIMSessionType sType, bool deleteSessions, OperateMsglogResultDelegate action));
参数 说明
sType 当前会话的类型,指定枚举类型NIMSessionType
deleteSessions 是否要同步删除会话列表项,true:删除,false:不删除,仅标记消息状态为已删除
action 操作结果回调通知
// 批量删除点对点消息记录
NIM.Messagelog.MessagelogAPI.DeleteMsglogsBySessionType(NIMSessionType.kNIMSessionTypeP2P,true,(code,msgId)=>
{
    ...
});

3. 删除所有历史记录

删除全部本地的历史消息,并可以选择同步删除会话列表项。

public static void ClearAll(bool deleteSessions, CommonOperationResultDelegate action);
参数 说明
deleteSessions 是否要同步删除会话列表项,true:删除,false:不删除,仅标记消息状态为已删除
action 操作结果回调通知
// 批量删除点对点消息记录
NIM.Messagelog.MessagelogAPI.ClearAll(true,(code,msgId)=>
{
    ...
});

修改消息状态

SDK 提供了修改消息为草稿等状态,也可以修改语音消息等的已播放和未播放的子状态

NIMMsgLogStatus消息状态

枚举 说明
kNIMMsgLogStatusNone 0 默认,不能当查询条件,意义太多
kNIMMsgLogStatusUnread 1 收到消息,未读
kNIMMsgLogStatusRead 2 收到消息,已读
kNIMMsgLogStatusDeleted 3 消息已删
kNIMMsgLogStatusSending 4 消息发送中
kNIMMsgLogStatusSendFailed 5 发送失败
kNIMMsgLogStatusSent 6 已发送
kNIMMsgLogStatusReceipt 7 对方已读发送的内容
kNIMMsgLogStatusDraft 8 草稿
kNIMMsgLogStatusSendCancel 9 发送取消
kNIMMsgLogStatusRefused 10 被对方拒绝,比如被对方加入黑名单等等

NIMMsgLogSubStatus消息子状态

枚举 说明
kNIMMsgLogSubStatusNone 0 默认
kNIMMsgLogSubStatusNotPlaying 1 未播放
kNIMMsgLogSubStatusPlayed 2 已播放

1. 设置消息状态

public static void SetMsglogStatus(string msgId, NIMMsgLogStatus status, OperateSingleLogResultDelegate action);
参数 说明
msgId 指定的消息唯一id
status 指定需要修改的状态
action 操作结果回调通知
// 设置client_msgid为kNIMMsgLogStatusSent状态;
NIM.Messagelog.MessagelogAPI.SetMsglogStatus("client_msgid",NIMMsgLogStatus.kNIMMsgLogStatusSent,(code,msgId)=>
{
    ...
});

2. 设置消息子状态

public static void SetMsglogSubStatus(string msgId, NIMMsgLogSubStatus status, OperateSingleLogResultDelegate action);
参数 说明
msgId 指定的消息唯一id
status 指定需要修改的消息子状态,详见NIMMsgLogSubStatus
action 操作结果回调通知
// 设置client_msgid为kNIMMsgLogStatusSent状态;
NIM.Messagelog.MessagelogAPI.SetMsglogSubStatus("client_msgid",NIMMsgLogSubStatus.kNIMMsgLogSubStatusPlayed,(code,msgId)=>
{
    ...
});

查询服务器消息历史

通过消息类型从服务器端获取消息历史,通过起止时间错和limit的显示来限制获取的范围。

public static void QueryMsglogOnline(string id, NIMSessionType sType, int limit, long sTimetag, long eTimetag,
    long endMsgId, bool reverse, bool saveLocal,bool autoDownloadAttach, QueryMsglogResultDelegate action);
参数 说明
id 会话id,对方的account id或者群组tid
sType 会话类型
limit 搜索结果的条数限制
sTimetag 起始时间戳,单位:毫秒
eTimetag 结束时间戳,单位:毫秒
endMsgId 结束查询的最后一条消息的服务器端消息id(server_msg_id)(不包含在查询结果中)
reverse true:反向查询(按时间正序起查,正序排列),false:按时间逆序起查,逆序排列(建议默认为false)
saveLocal true: 将在线查询结果保存到本地,false: 不保存
autoDownloadAttach 查询结果回来后,是否需要sdk自动下载消息附件(暂时不支持),默认由全ClientAPI.Init传入的NimUtility.NimConfig来控制
action 查询结果回调
NIM.Messagelog.QueryMsglogOnline(id, sType, limit, sTimetag, eTimetag,
    endMsgId, false, true, true, (code, accountId, sType, result) =>
{
    if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
})

导入导出消息历史

SDK为了方便用户,提供导入和导出消息历史文件的接口,必须提供导入或者导出文件的绝对路径。

导出消息历史

导出整个消息历史DB文件(不包括系统消息历史,android 和 ios 平台下不可用)

public static void ExportDatabaseFile(string destPath, CommonOperationResultDelegate action);
参数 说明
destPath 导出时保存的目标绝对路径,必须保证该路径下可写入文件
action 操作结果回调通知
//以windows平台路径为例
NIM.Messagelog.MessagelogAPI.ExportDatabaseFile("D:\\msg.db",(code)=>
{
    ...
});

导入消息历史

导入消息历史记录(不包括系统通知),且不允许拿别人的消息历史记录文件来导入。调用此接口需要传入消息历史文件的绝对路径。

public static void ImportDatabase(string srcPath, CommonOperationResultDelegate action, ImportProgressDelegate prg);
参数 说明
srcPath 导出时保存的目标绝对路径,必须保证该路径下可写入文件
action 操作结果回调通知
prg 操作进度回调通知
//以windows平台路径为例
NIM.Messagelog.MessagelogAPI.ImportDatabase("D:\\msg.db",(code)=>
{
    ...
},(importedCount, totalCount)=>
{
    //通知操作进度
    ...
});