Chat

Chat is an encapsulation of common chat requirements for a quick integratin with IM.

This document introduces to you the related concepts and considerations. For more details on the usage, please refer to the corresponding integration guide and API documentation when using it.

User

That are users, referring to the people participating in chat sessions, i.e, the service object of the application. Single chat can be initiated between users.

User Authentication

For applying a quick access to the existing user system, the Realtime Engine authenticates the user in a callback to complete the user sign-in. For the details on the authentication process, see User Authentication.

Every user is supposed to have a unique userId as the unique identification of the user in the Chat system. This userId usually belongs to the existing user system of the application, and it is bound to the current connection when calling the sign-in interface through the above user authentication process.

Group

That are groups. A user can create groups and invite others to join, and the chats among group members are called group chat.

Every group has a unique groupId, which is created by the Realtime Engine when calling the corresponding interfaces.

Note that the server of the Realtime Engine only maitains the relationship among group members so as to route and send group chat messages. Such information as group name and description should be maintained by the application itself, and correlate with them according to groupId.

Conversation

That are chats. Every chat, whether single chat or group chat, every participant, whether sending messages actively or receiving messages passively, a conversation will be automatically generated on the server from each perspective (if not existing before or deleted).

The conversations everyone sees has their own unread messages (unreadMessageCount). When the counterpart is sending messages, no matter whether the user is online or not, this value will automatically increase. Usually the application needs to actively call the related interface to reset the value as 0 when users enter or leave the conversation interface.

Conversations can be deleted, which only takes effect to the action taker but not other users.

Message

That are messages. Usually each SDK places the interface of sending messages in the conversation. The objects such as conversation.sendMessage() and conversation are probably the conversation histories loaded from server or created temporarily locally. When you send messages to one of them, the single chat user or group users the conversation correlated with will all receive the messages and a corresponding conversation will be generated.

Message Category

Messages can be categorized as follows in line with the content.

Text Message: used to send common texts.
Image Message: used to send images.
Audio Message: used to send audios. The SDK will provide the corresponding helper class for recording and playing.
Video Message: used to send videos. The SDK will provide the corresponding helper class for recording and playing.
Location Data Message: used to send longitude and latitude. The SDK will provide the helper class for acquiring longitude and latitude.

Among which, graphic, audio and video messages are also called multimedia messages, and are sent through two steps:

Upload corresponding files to distributed file servers.
Send messages to the recipients, and then the recipients can download files to process.

In addition, every message can have an extra field, which is the additional information used to implement the custom business logic of the application under the circumstances of the above message types not able to satisfy the application requirements.

Parameter Explanation when Loading Message History

Every message has a messageId, and it increments independently in each conversation to make it easy for the developer to sort according to ID. The interfaces provided by each SDK for loading message history all need to offer startMessageId, endMessageId and limit. Please see the usage below:

endMessageId	startMessageId	limit	return	comments
-	-	-	latest 20 messages
11	-	-	20 messages from 11 (included), i.e., 11~30
11	-	50	50 messages from 11 (included), i.e., 11~60
10	40	-	20 messages from 10 (included) to 29 (included)	due to restriction by `limit`
10	40	31	31 messages from 10 (included) to 40 (included)
-	40	-	20 messages from 21 (included) to 40 (included)
-	40	30	30 messages from 11 (included) to 40 (included)	Recommended! Get the latest 20 messages first, and then get in turn in this way

Note that the sequence of message load starts from new to old, and so does message return.

Cache Policy

To save traffic, each SDK will cache partial data locally so as to reduce unnecessary network transport:

When loading group and conversation lists, only request the data updated since last sync from the server, and merge with the local data after getting the new data.
When loading message history, determine the message scope according to startId and endId. Only when the local cache doesn’t contain certain messages in this scope can those messages be retrieved from the server.
All the changes to group and conversation will be synchronized to the local cache after calling the server successfully.

Offline Function

In case the cache has been enabled, the SDK can support the offline function, i.e., when the network is unavailable, the SDK supports the invocation of certain APIs. If the user has not yet signed in or signed out alreay, all the APIs are not available. If the user has signed in, different APIs will have different behaviors:

When signing in, if within the offline duration that is set, the user information of last successful sign-in will be used.
When signing out, user information in local cache will be cleared, and sign-out is successful.
Acquiring resource-related API will return the data in local cache.
Messages sent will be first cached locally and labelled as sending, and then resent automatically when network is restored.
Other requests will have time-out handling.

When initializing the Engine, the following parameters can be configured:

supportOffline: whether to enable the offline function, true by default.
maxOfflineTime: maximum offline duration (sec), -1 indicating eternal, 30 days by default (compared with last online time). This parameter is valid only when supportOffline is true .