Local Record

A relatively complete message record management feature is provided, which allows developers to view, delete and clear (local and online) chat history, and also to write message records，and import/export historical messages (import only supports records of the current user). Also note that: Operations (such as deletion) on and status changes (such as sending failed or successful) of local message history will be automatically synchronized to the message status in the session list, so the App Upper's processing of corresponding notification event should be based on the callback for monitored session list notification

Global Notification of Message Status Change

Register the global notification of message status change (currently only covers read status change). Upon receiving message read status from the other party, the caller will be notified through this registered callback.

• API prototype

public static void RegMsglogStatusChangedCb(MsglogStatusChangedDelegate cb);

• Example

//Register global notification of message status change
NIM.Messagelog.MessagelogAPI.RegMsglogStatusChangedCb((code，result)=>
{
	//Result - json character string, example: [{"talk_id":"test1","msg_timetag":"1520500638234","status":2}]
	...
});

Query Message History

SDK provides an interface for querying local message history] based on anchor time, and the results of which are sorted according to time (searched in reverse order of time, with results sorted in reverse order).

• API prototype

public static void QueryMsglogLocally(string accountId, NIMSessionType sType, int limit, long msgAnchorTimetag, QueryMsglogResultDelegate action)

• Parameter Description

Parameter	Description
accountId	Session ID, account ID of the other party or team tid
sType	Session type
limit	Number of sessions for one query, 20 is the recommended value
msgAnchorTimetag	The timestamp of the last message of the last query (searched in reverse order of time, so the result is the smallest timestamp)
action	Query result callback notification

• Example

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)
        {
            ···
        }
    }
});

Query Local Message History Covering Starting and Ending Time

The application method of the interface is similar to "Query message history", can query earlier or later messages by MsgAnchorTimttag time and return limit records. If the quantity is smaller than limit, actual quantity will be returned. Now, it is available to support Direction only based on "Query message history", instead of EndTimetag and Reverse.

• API prototype

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

• Parameter Description

Description for the important parameter QueryMsglogParams

Type	Parameter	Description
string	AccountId	Session ID, account ID of the other party or team tid
NIMSessionType	SessionType	Session type
int	CountLimit	The upper limit of messages to be queried. The number must be greater than 0.
long	MsgAnchorTimttag	Timestamp for anchor point of query time (unit: ms)
long	EndTimetag	Timestamp for end time of query time (unit: ms), unavailable temporarily
MsglogSearchDirection	Direction	Query earlier or later messages
bool	Reverse	"true" means reverse query (query and rank by time in positive sequence). "false" means query and rank by time in reversed order. (It is recommended to set to "false"), unavailable temporarily.

Description of the property MsglogSearchDirection:

Enumeration	Value	Description
kForward	0	Query message earlier than anchor time
kBackward	1	Query message later than anchor time

• Example

// Taking P2P as an example, testAccount is a test account
QueryMsglogParams param = new QueryMsglogParams{
	AccountId="testAccount is test account",
    SessionType=kNIMSessionTypeP2P,
    CountLimit = 20,
    MsgAnchorTimttag = 1519977874123,//13-byte timestamp, unit: ms
    EndTimetag = 1519978139567，//13-byte timestamp, unit: ms
    Direction = MsglogSearchDirection.kBackward
};
NIM.Messagelog.MessagelogAPI.QueryMsglogLocally(param, (code, accountId, sType, result) =>
{
	if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
});

Message Query based on Message uuid

• API prototype

public static void QuerylogById(string clientMsgId, QueryLogByMsgIdResultDelegate action);

• Parameter Description

Parameter	Description
clientMsgId	Message ID used in the query
action	Query result callback notification

• Example

string clientMsgId="msg_id";//follow the actual message ID
MessagelogAPI.QuerylogById(clientMsgId, (code, msdId, msg)=>
{
    ...
});

Query Local Messages based on Specified Conditions

Query local messages based on specified conditions. This interface can be used to perform features such as global search. For details, please refer to the development manual. Currently, it only supports queries by a single ID, which means you can add only oneidsuid for the query.searchContent The parameter cannot be null.

• API prototype

 public static void QueryMsglogByCustomCondition(NIMMsgLogQueryRange range, string[] ids, int limit,
            long sTimetag, long eTimetag, string endMsgId, bool reverse,
            NIMMessageType msgType, string searchContent, QueryMsglogResultDelegate action)；

• Parameter Description

Parameter	Description
range	Searchable range of message history
ids	Session ID, a collection of other parties' account ids or team tids, currently only single ID query is supported
limit	Quantity limit for query results
sTimetag	Starting timestamp, unit: milliseconds
eTimetag	Ending timestamp, unit: milliseconds
endMsgId	client_msg_id of the last message at the end of query (not included in the query results) (not enabled for the time being)
reverse	true: reverse query (searched in positive order by time, sorted in positive order), false: searched in reverse order by time, sorted in reverse order (recommended default is false)
msgType	Searchable message types (only three types are supported for the time being, namely kNIMMessageTypeText, kNIMMessageTypeImage and kNIMMessageTypeFile)
searchContent	Text search (currently only keyword search in text and file name) is available for two types of messages, kNIMMessageTypeText and kNIMMessageTypeFile. Combined search requires using kNIMMessageTypeUnknown
action	Query result callback

NIMMsgLogQueryRange Enumeration type

Enumeration	Value	Description
kNIMMsgLogQueryRangeP2P	0	Specified user (p2p session) (Note: Search by specifying multiple users is not supported for the time being!)
kNIMMsgLogQueryRangeTeam	1	Specified team (Note: Search by specifying multiple teams is not supported for the time being!)
kNIMMsgLogQueryRangeAll	100	All
kNIMMsgLogQueryRangeAllP2P	101	All individual sessions
kNIMMsgLogQueryRangeAllTeam	102	All teams
kNIMMsgLogQueryRangeUnknown	200	Query not supported

• Example

//Take P2P message as an example
string[] ids = new string[]();
ids.add("testAccount");
long sTimetag = 1519977874123;//13-byte timestamp, unit: ms
long eTimetag = 1519978139567;13-byte timestamp, unit: ms, require to be later than sTimetag, i.e. 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)
        {
            ···
        }
    }
})

Insert Local Message

Save the message to the local database. If the message already exists, it will be updated without being sent to the server. Make sure that the entire message conforms to content requirements for messaging.

• API prototype

public static void WriteMsglog(string uid, bool need_update_session, NIMIMMessage msg, OperateSingleLogResultDelegate action);

• Parameter Description

Parameter	Description
uid	Session ID, account ID of the other party or team tid
need_update_session	Whether to update the session list (generally required for the latest message)
msg	For message body, see NIMIMMessage
action	Callback function of operation result

• Example

//Create a text message, taking the receiver's testAccount as an example
NIMTextMessage msg = new NIMTextMessage();
msg.ClientMsgID="uuid";//Unique ID of the message
msg.TalkID="testAccount"; account of the other party
msg.ReceiverID="testAccount"; account of the other party
msg.TimeStamp=1519977874123;//13-byte timestamp, unit: ms
msg.MsgLogStatus=NIMMsgLogStatus.kNIMMsgLogStatusDraft;//The status of other messages can be set.
msg.TextContent="111";
...
// Save a message to local database, but not send it to server
NIM.Messagelog.MessagelogAPI.WriteMsglog("testAccount",true, msg, (code, msgId)=>
{
	...
});

Delete Message History

You can delete a message with a specified msgid, or delete messages in batches.

1. Delete a specified message

Delete message history according to specified receiver account or team ID, msgID

• API prototype

public static void DeleteSpecifiedMsglog(string sid, NIMSessionType sType, string msgId, OperateSingleLogResultDelegate action);

• Parameter Description

Parameter	Description
sid	Receiver account or team ID
sType	Type of current session, specified enumeration typeNIMSessionType
msgId	Specify the unique ID of the message to be deleted
action	Callback notification of operation result

• Example

//Taking p2p messages of the testAccount as an example
NIM.Messagelog.MessagelogAPI.DeleteSpecifiedMsglog("testAccout",NIMSessionType.kNIMSessionTypeP2P,"client_msgid",(code,msgId)=>
{
	...
});

2. Delete all messages of the specified session type

Delete the history from the sTypespecified in the notification, operation is only performed to local database without syncing with the server.

• API prototype

public static void DeleteMsglogsBySessionType(NIMSessionType sType, bool deleteSessions, OperateMsglogResultDelegate action));

• Parameter Description

Parameter	Description
sType	Type of the current session, specifying the enumeration type NIMSessionType
deleteSessions	Whether to delete the session list item synchronously, true: delete, false: do not delete, only tagging message status as deleted
action	Callback notification of operation result

• Example

// delete p2p message records in batches
NIM.Messagelog.MessagelogAPI.DeleteMsglogsBySessionType(NIMSessionType.kNIMSessionTypeP2P,true,(code,msgId)=>
{
	...
});

3. Delete all history

Delete all local message history, with or without deleting corresponding session list items synchronously.

• API prototype

public static void ClearAll(bool deleteSessions, CommonOperationResultDelegate action);

• Parameter Description

Parameter	Description
deleteSessions	Whether to delete the session list item synchronously, true: delete, false: do not delete, only tagging message status as deleted
action	Callback notification of operation result

• Example

// delete p2p message records in batches
NIM.Messagelog.MessagelogAPI.ClearAll(true,(code,msgId)=>
{
	...
});

Update Message Status

The SDK supports updating message status to draft, etc., and sub-status of voice messages, such as played and unplayed, etc.

NIMMsgLogStatusMessage status

Enumeration	Value	Description
kNIMMsgLogStatusNone	0	Default, it's meaning is too varied and therefore can't be used as a query condition
kNIMMsgLogStatusUnread	1	Received, unread
kNIMMsgLogStatusRead	2	Received, read
kNIMMsgLogStatusDeleted	3	Message deleted
kNIMMsgLogStatusSending	4	Message sending
kNIMMsgLogStatusSendFailed	5	The message is not sent successfully
kNIMMsgLogStatusSent	6	Message sent
kNIMMsgLogStatusReceipt	7	The other party has read the content sent
kNIMMsgLogStatusDraft	8	Draft
kNIMMsgLogStatusSendCancel	9	Cancel send
kNIMMsgLogStatusRefused	10	Rejected by the other party, due to reasons such as being blacklisted.

NIMMsgLogSubStatusMessage substatus

Enumeration	Value	Description
kNIMMsgLogSubStatusNone	0	Default
kNIMMsgLogSubStatusNotPlaying	1	Not played
kNIMMsgLogSubStatusPlayed	2	Played

1. Set message status

• API prototype

public static void SetMsglogStatus(string msgId, NIMMsgLogStatus status, OperateSingleLogResultDelegate action);

• Parameter Description

Parameter	Description
msgId	Unique ID of the specified message
status	Specify the status that needs to be updated
action	Callback notification of operation result

• Example

// Set client_msgid to kNIMMsgLogStatusSent;
NIM.Messagelog.MessagelogAPI.SetMsglogStatus("client_msgid",NIMMsgLogStatus.kNIMMsgLogStatusSent,(code,msgId)=>
{
	...
});

2. Set message sub-status

• API prototype

public static void SetMsglogSubStatus(string msgId, NIMMsgLogSubStatus status, OperateSingleLogResultDelegate action);

• Parameter Description

Parameter	Description
msgId	Unique ID of the specified message
status	For sub-status of designated message to be updated, see NIMMsgLogSubStatus.
action	Callback notification of operation result

• Example

// Set client_msgid to kNIMMsgLogStatusSent;
NIM.Messagelog.MessagelogAPI.SetMsglogSubStatus("client_msgid",NIMMsgLogSubStatus.kNIMMsgLogSubStatusPlayed,(code,msgId)=>
{
	...
});

Query Server Message History

Get the message history of specific types from the server by specifying the start and end time as well as display limit.

• API prototype

public static void QueryMsglogOnline(string ID, NIMSessionType sType, int limit, long sTimetag, long eTimetag,
    long endMsgId, bool reverse, bool saveLocal,bool autoDownloadAttach, QueryMsglogResultDelegate action)；

• Parameter Description

Parameter	Description
ID	Session ID, account ID of the other party or team tid
sType	Session type
limit	Quantity limit for query results
sTimetag	Starting timestamp, unit: milliseconds
eTimetag	Ending timestamp, unit: milliseconds
endMsgId	Session ID at server for final message of end query (server_msg_id) (not included in query results)
reverse	true: reverse query (searched in positive order by time, sorted in positive order), false: searched in reverse order by time, sorted in reverse order (recommended default is false)
saveLocal	true: Save online query results to local database, false: Not to save
autoDownloadAttach	Whether sdk automatically downloads message attachment (unavailable now) after querying results. By default, it is controlled by NimUtility.NimConfig that is input via global ClientAPI.Init.
action	Query result callback

• Example

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)
        {
            ···
        }
    }
})

Import and Export Message History

For the convenience of users, SDK provides interfaces for importing and exporting message history files, for which absolute path of the import or export file must be provided.

Export Message History

Export DB file of the entire message history (excluding system message history, not available for android and ios platforms)

• API prototype

public static void ExportDatabaseFile(string destPath, CommonOperationResultDelegate action);

• Parameter Description

Parameter	Description
destPath	The target absolute path saved when exporting, must ensure that write operation is allowed in this path
action	Callback notification of operation result

• Example

//Take the windows platform as an example
NIM.Messagelog.MessagelogAPI.ExportDatabaseFile("D：\\msg.db",(code)=>
{
	...
});

Import Message History

Import message history (excluding system notifications, and never import other's message history files). Calling this interface requires inputting the absolute path of message history.

• API prototype

public static void ImportDatabase(string srcPath, CommonOperationResultDelegate action, ImportProgressDelegate prg);

• Parameter Description

Parameter	Description
srcPath	The target absolute path saved when exporting, must ensure that write operation is allowed in this path
action	Callback notification of operation result
prg	Operation progress callback notification

• Example

//Take the windows platform as an example
NIM.Messagelog.MessagelogAPI.ImportDatabase("D：\\msg.db",(code)=>
{
	...
},(importedCount, totalCount)=>
{
    //Notification about operation progress
	...
});