Message types

Messages in IM SDK include in-session messages and system notification messages.

In-session messages

In-session messages are displayed in the chat API, which is sent between users, teams, or chat rooms. In-session messages include text and pictures. In-session messages supported by IM SDK currently include:

Types	Description
Text	The message content is plain text.
Image messages	The message content includes the URL, dimensions, and size of the image.
Voice messages	The message content includes the URL, dimensions, duration, size, and format of audio files.
Video messages	The message content includes the URL, dimensions, duration, size, and format of video files.
File messages	A video message includes such information as the URL, duration, size, and format of any video file.
Location messages	The message content includes the caption, longitude, and latitude of the location.
Team event notification messages	This is a notification of team events, which is issued by the server. No team event notification message can be sent by the client. Notification messages include online, offline and roaming mechanism, without a notification bar.
Tip messages	Without push notification or notification bar, the tip message is mainly used as a notification in sessions, such as a welcome message when ready for a session, or any tip message after sensitive words display in the session.
Custom messages	Message types that are customized by developers, such as red packet and rock-paper-scissor.

System notification messages

A system notification message is a type of system-level message, which is generally sent by the system to a user or a team. System notification messages include built-in and custom ones.

• Built-in system notifications are notifications pre-defined by SDK. The notification message pushed by CommsEase server to users is for event notifications. Built-in system notifications currently include the notifications related to team changes, such as applications for joining a team, and team invitation. If the third-party app also enables friendship hosting, adding or removing friends are also included in event notifications. The SDK receives and stores system notifications, provides unread counts. Only online and offline messages are available, and neither roaming messages nor push notifications are provided.
• Custom system notifications refer to some notifications of event status defined by the developer, and can be sent by both the client and the server. Without storing or parsing the notifications, SDK is only used to transmit and notify such events on behalf of a third party to achieve pass-using purposes, and the upper layer developer is responsible for the persistent work after custom notification.

Type	Message storage	Unread count	Offline messages	Roaming messages	Message push
Built-in system notification	Yes	Yes	Yes	No	No
Custom system notification	No	No	Yes	No	Yes

For the specific platform development guide for system notification messages, see:

• iOS: System Notification
• Android: System Notification
• Windows: System Notification
• Web: System Notification
• Linux: System Notification
• Unity: System Notification
• Cocos2d-x: System Notification
• Server: System Notification

Concepts

Notification messages and system notifications

• Concept

Notification messages are messages in sessions (Within the session), including online messages, offline messages, and roaming messages. Such messages are currently used for notification of already completed team events, and are not included in the unread count. Neither push notifications nor notification bars are available.

System notifications are built in by CommsEase, which are sent by CommsEase server to users for notification of CommsEase system events. System notifications mainly include team change notifications, such as applications for joining a team and team invitation. If the third-party app also hosts friendship, addition and removal of friends are also included in this type of notification. System notifications are received and stored by SDK that supports simple management of unread count. Only online and offline notifications are available, and no roaming notifications are provided. Neither push notification nor notification bar is available (if required, custom system notifications are sent).

• Scenarios

Notification messages are generally in the middle of the chat API. For example, a team name has been updated; XXX quit the team chat, etc.

System notifications are generally displayed in the list of verification messages. For example, xxx requested to add you as a friend, etc.

Custom message and custom system notifications

• Concept

Custom messages are in-session messages mainly provided to third-party developers for customizing messages, including online, offline and roaming messages, as well as tips in a notification bar. Global messages defined by a third party only include online and offline messages instead of roaming ones.

The difference between custom notifications and custom messages is that the latter is a part of the in-session message system, stored by SDK in the message database, and displayed to users together with other built-in messages of CommsEase. Custom notifications are mainly used for notification of third-party event status. Without storing or parsing the notifications, CommsEase is only used to store and notify such events on behalf of a third party to achieve pass-using purposes.

• Scenarios

Custom messages, as texts and voice messages, are at the left and right of the chat API. Stickers, rock-paper-scissors, and self-destructing messages are custom messages.

Custom system notifications are typically seen in one-to-one chat, with " typing status indicator" displayed.

Message features

In addition to various message types, IM SDK also provides common message features.

Message features	Description
Offline messages	Messages are received when a user is offline. When the user logs in, the client SDK will get automatically stored offline messages. One-to-one chat: Offline users can receive the latest 5000 messages sent within 30 days. The maximum number of one session is 100. Team chat: Offline users can receive messages sent within 30 days. The maximum number of one session is 100.
Roaming message	At login on a new device (or uninstalled and reinstalled), the roaming messages recorded in the server will be auto-synced to the client SDK. Roam the recent 100 sessions within 7 days, and the recent 100 messages in each session
Multi-device synchronization	When multiple devices are concurrently online, messages are synchronized and received across multiple devices.
Historical messages	Both local and cloud historical messages are supported. Standard edition: you can receive cloud historical messages in the past year. With the value-added service enabled, you can receive cloud historical messages for the past three years.
Recall message	Recall a message that has been delivered successfully. By default, messages that were delivered more than 2 minutes ago cannot be recalled. Only one-to-one and group chat messages can be recalled. Messages sent in chat rooms cannot be recalled.
Read receipt	View the read and unread status in the one-to-one chat and team chat.
Forward messages	Users can forward messages to other users or groups.
@mentions	Message extension field is used for realization. To mention somebody when sending a team message, a team message may be sent with the mentioned account list with an extension field; upon receipt of the team message, team members may check whether they are in the mentioned account list; if yes, they will receive a tip "you were mentioned" on The API.
Typing status indicator	For more information, see Send custom system notifications.

Recent sessions

Recent session, known as the recent contact list, records the information of contact who recently had a session with the users, including the account and type of contact, time of recent message, message status, content, and unread count.

In relation to the recent session list, SDK maintains and provides The API for querying and monitoring changes. As long as there is any chat with a user or team ( sends or receives messages), SDK will automatically update the recent session list and notify the upper level, and the developer is not required to manually update the session list.

In some cases, the developer might manually insert a session (i.e. a recent contact) in the recent session list. For example, after creating an advanced team, it is required to display the team sessions in the recent session list. No messages will be received when an advanced team is created. SDK will not immediately update recent sessions. To satisfy the demands, a local message may be inserted in the callback of successful creation of a team to insert a session.

Particularly, recent sessions are local, and will not roam. After login on a new device, the recent session list will be automatically generated based on the current roaming and offline messages.