Generation rules

The SDK will generate the list of initial sessions based on roaming messages and offline messages. After receiving and sending messages, SDK will update the list of sessions.

Initialization parameters

• Not all initialization parameters are listed here. Please refer to Initialize SDK, and initialization parameters are given in other chapters.
  • Initialization parameters for connection
  • Initialization parameters for multi-device login
  • Initialization parameters for messages
  • Initialization parameters for team
  • Initialization parameters for user profile
  • Initialization parameters for friendship
  • Initialization parameters for user relationship
  • Initialization parameters for session
  • Initialization parameters for system notifications
  • Synchronization completed
  • Complete initialization codes

Sample codes

javascriptvar nim = NIM.getInstance({
    onsessions: onSessions,
    onupdatesession: onUpdateSession
});
function onSessions(sessions) {
    console.log('Receive session list', sessions);
    data.sessions = nim.mergeSessions(data.sessions, sessions);
    updateSessionsUI();
}
function onUpdateSession(session) {
    console.log('session is updated', session);
    data.sessions = nim.mergeSessions(data.sessions, session);
    updateSessionsUI();
}
function updateSessionsUI() {
    // Refresh The API
}

Parameter description

• syncSessionUnread: It determines to synchronize unread count of sessions. By default, the unread count of sessions are not synchronized.
  • If you select to synchronize unread count
    • the session read on one client will also be marked as "read" on other devices
    • When invoking The API Set current sessions,the SDK will synchronize unread count automatically. If current session message is received later, The API Reset unread count of session shall be invoked manually to synchronize unread count.
• onsessions: It is a callback for synchronizing the list of recent sessions, which will input the sessions list. The sessions are sorted in positive sequence by time. Namely, recent sessions are ranked at the end of list.
  • It is an increment callback, which can invoke nim.mergeSessions to merge data.
• onupdatesession: It is a callback for updating session, which will input Session object. The callback will be returned if you:
  • Receive message
  • Send messages
  • Set current session
  • Reset unread count of sessions

Session object

The session object contains fields as below:

• id: Session ID
• scene: Scene.
• to: Chat object, account or team ID.
• updateTime: Update time of session
• unread: Unread count
• lastMsg: Final message of the session
• msgReceiptTime: Timestamp of acknowledged receipt. If the field is not null, it means that all messages before the timestamp are acknowledged.
  • Now, it is available to 'P2P' session only.
  • The field can be seen only when acknowledged receipt is sent.
  • The API Send acknowledged receipt of message can be invoked to send acknowledged receipt of message.
  • The API Query acknowledged status of message can be invoked to query that a message is acknowledged.
• localCustom: Local custom extension field
  • When Support database is available, The API Update local session can be invoked to update the field to local database only, instead of the server

Unread count

The SDK will automatically manage unread count of sessions. unread Of session object is unread count is sessions. If developers find that unread count of session is larger than offline message count, it is necessary to Get unread message from local database.

Under different configuration environment, initialization for unread count of sessions is designed with different calculation rules:

• Enable database: db = true
  • Enable the feature of synchronizing unread count of sessions: syncSessionUnread = true
    • The unread count of session is compared with local session history in local database using server pushed Ack or locally stored Ack timestamp. If it is later than Ack and not equal to the count of your messages, it is unread count.
    • Please refer to Initialization parameters for session.
  • Disable the feature of synchronizing unread count of sessions: syncSessionUnread = false
    • Now, the unread count of session is acquired from last unread count recorded in a local database. If there are offline messages and message attributes are marked as "isUnreadable", the corresponding number is added to original unread count.
• Disable database: db = false
  • Disable the feature of automatically marking message as acknowledged: autoMarkRead = false
    • Now, all offline messages that are pushed by server are considered as unread and roaming messages is considered as acknowledged.
  • Enable the feature of automatically marking message as acknowledged: autoMarkRead = true
    • Every time offline message is received, the server will be notified that the message is acknowledged. Next time when you log in, the server will not push offline messages, but mark them as roaming messages. There is not any offline message, and unread count is 0.
    • Please refer to Mark messages as received.

Set current session

• If there is session history, unread count of the session will be set to 0, and developers will receive the callback onupdatesession.
• The session will not update unread count later after receiving any message.

javascriptnim.setCurrSession('sessionId')

Reset unread count of sessions

• If the session history exists, unread count of the session will be set to 0, and the callback onupdatesession will be returned.
• The session will update unread count later after receiving any message.

javascriptnim.resetSessionUnread('sessionId')

Reset unread count of all sessions in memory

• If the session history is in memory, unread count of all sessions in the memory will be reset, and the callback onupdatesession will be returned repeatedly.
• The session will update unread count later after receiving any message.

javascriptnim.resetAllSessionUnread()

Reset current session

• After the current session is reset, all sessions will update unread count after receiving any message.

javascriptnim.resetCurrSession();

Get a list of local sessions

• When Support database is available, the SDK will store sessions to database, and return session lists to developers with the callback onsessions at initialization. But the maximum number of sessions in the list is 100.
• To get more session histories, you can invoke The API.
• lastSessionId is id of the last session in last query. It is null for the first time.
• limit is the limit of queried sessions. The maximum number is 100, which is also the default value.
• By default, query local sessions by starting from the recent session. The parameter reverse=true can be input to query local session backward starting from the first session.

javascriptnim.getLocalSessions({
    lastSessionId: lastSessionId,
    limit: 100,
    done: getLocalSessionsDone
});
function getLocalSessionsDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('get local session list' + (!error?'succeeded':'failed'));
    if (!error) {
        onSessions(obj.sessions);
    }
}

Get local session with sessionId

• When "Support database" is available, corresponding session is queried in database. If there is such session, the session object will be returned, otherwise, null will be returned.
• When "Support database" is not available, the previously synchronized sessions list is queried in database. If there is such session, the session object will be returned, otherwise, null will be returned.
• sessionId is sessionId of the session to be queried.

javascriptnim.getLocalSession({
    sessionId: sessionId,
    done: getLocalSessionDone
});
function getLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('get local session actions' + (!error ? 'succeeded': 'failed'), error, obj)
    if (!error) {
        onSession(obj);
    }
}

Designate lastMsg type to get a list of local sessions

• The sessions that are sorted in reversed order by time and contain designated messages are returned. Exclude message types with the parameter exclude, and specify designated types. lastMsg is the recent and required message in returned messages. The maximum number of messages are 100.
• For detailed parameters and application, see API Document

Insert a local session history

• Developers can insert a local session history. When "Support database" is available, the SDK will store the session to local database, otherwise, the data will be stored in memory only.
• The SDK will set a time that is later than update time of all current sessions as update time of the session, or developers can input the parameter updateTime to designate the update time.
• In the callback, developers need to save generated sessions.

javascriptnim.insertLocalSession({
    scene: 'p2p',
    to: 'account',
    done: insertLocalSessionDone
});
function insertLocalSessionDone(error, obj) {
    console.log('insert local session records' + (!error?'succeeded':'failed'), error, obj);
    if (!error) {
        onSessions(obj.session);
    }
}

Update local sessions

• Update local sessions corresponding to id.
• If it does not support database, local sessions are successfully updated.
• If there is no related session, local sessions are successfully updated and return null.
• These fields will be updated to a local database, instead of the server.
• Currently, only localCustom is allowed to be updated.

javascriptnim.updateLocalSession({
    id: 'p2p-account',
    localCustom: '{"key","value"}',
    done: updateLocalSessionDone
});
function updateLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('update local sessions' + (!error?'succeeded':'failed'));
}

Delete local sessions

• When "Support database" is available, if local session is deleted, it will not be synchronized to corresponding session next time.
• If it does not support database, local sessions are successfully deleted.
• If there is no related session, local sessions are successfully deleted.
• The parameter ID is session ID or ID array.

javascriptnim.deleteLocalSession({
    id: 'p2p-account',
    done: deleteLocalSessionDone
});
function deleteLocalSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('delete local sessions' + (!error?'succeeded':'failed'));
}

Delete sessions in server

• When "Support database" is available, if sessions in server are deleted, corresponding sessions and roaming messages are not synchronized next time. In addition, they cannot be synchronized to corresponding sessions and roaming messages on new devices.
• scene Please refer to Message scenarios.
• to: Account of the other party or team ID.

javascriptnim.deleteSession({
    scene: 'p2p',
    to: 'account',
    done: deleteSessionDone
});
function deleteSessionDone(error, obj) {
    console.log(error);
    console.log(obj);
    Console.log('delete sessions from the server' + (!error?'succeeded'':'failed'));
}

Delete sessions in server in batches

• When "Support database" is not available, if sessions in server are deleted, corresponding sessions and roaming messages are not be synchronized next time. In addition, corresponding sessions and roaming messages can not be synchronized on new devices.
• When "Support database" is not available, if sessions in server are deleted, corresponding sessions and roaming messages are not be synchronized next time. In addition, corresponding sessions and roaming messages can not be on new device.
• When "Support database" is not available, if sessions in server are deleted, corresponding sessions and roaming messages are not be synchronized next time. In addition, corresponding sessions and roaming messages can not be on new device.
• scenePlease refer to Message scenarios.
• to: Account of the other party or team ID.

javascriptnim.deleteSessions({
    sessions: [{
        scene: 'p2p',
        to: 'account'
    }, {
        scene: 'p2p',
        to: 'account1'
    }],
    done: deleteSessionsDone
});
function deleteSessionsDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('delete sessions in batch' + (!error?'succeeded'':'failed'));
}

Server sessions list

V7.0.0 and later support the server sessions list which is a new service and different from "recent session" of SDK, and can be separated completely.

"Recent session" is generated and kept by SDK, while server sessions list is kept by server to record over 100 sessions, without attributes such as unread and msgReceiptTime.

The SDK provides following APIs for developers, change and delete sessions at server client.

• Get list of server sessions
• Get a session on server
• Update extension field of a session on server
• Delete some sessions from list of sessions on server

At multi-device login, if one client updates extension fields of the server session, the SDK will notify developers with the callback function onSyncUpdateServerSession. You can input the monitoring function when initializing the SDK.