Instant Messaging
Getting Started
Account Integration and Login
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Interface Overview
Integrate and Initialize SDK
Basic Messaging
Message History
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
Push and Message Alert
Chat Room
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
API Reference
Status Codes

Basic Message Features

Update time: 2022/06/28 18:39:36

Message types

Messages in IM SDK include conversation messages and System notifications.

Conversation messages

Conversation messages are displayed in the chat page, which is sent between users, groups, or chat rooms. Conversation messages include text and pictures. Conversation 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.
Group event notification messages This is a notification of group events, which is issued by the server. No group 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 conversations, such as a welcome message when ready for a conversation, or any tip message after sensitive words display in the conversation.
Custom messages Message types that are customized by developers, such as red packet and rock-paper-scissor.

System notifications

A system notification is a type of system-level message, which is generally sent by the system to a user or a group. System notifications 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 group changes, such as applications for joining a group, and group 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 notifications, see:


Notification messages and system notifications

  • Concept

Notification messages are messages in conversations, including online messages, offline messages, and roaming messages. Such messages are currently used for notification of already completed group events, and are not included in the unread count. Neither push notifications nor notification bars are available for notification messages.

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 group change notifications, such as applications for joining a group and group 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 usually appear on the chat page. For example, a group name has been updated, a user quit the group, etc.

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

Custom message and custom system notifications

  • Concept

Custom messages are conversation 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 conversation 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 page. Stickers, rock-paper-scissors, and self-destructing messages are custom messages.

Custom system notifications are typically seen in one-to-one chat, such as the "Typing" notification shown on the chat page when your partner is typing.

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 conversation is 100. group chat: Offline users can receive messages sent within 30 days. The maximum number of one conversation 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 conversations within 7 days, and the recent 100 messages in each conversation
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 group 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 group message, a group message may be sent with the mentioned account list with an extension field; upon receipt of the group message, group 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 conversation

Recent conversations, known as the recent contact list, records the information of contact who recently had a conversation 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 conversation list, SDK maintains and provides The API for querying and monitoring changes. As long as there is any chat with a user or group ( sends or receives messages), SDK will automatically update the recent conversation list and notify the upper level, and the developer is not required to manually update the conversation list.

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

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

Was this topic helpful?
  • Message types
  • Conversation messages
  • System notifications
  • Concepts
  • Notification messages and system notifications
  • Custom message and custom system notifications
  • Message features
  • Recent conversation