Basic Messaging

Update time: 2023/01/18 15:40:16

Message types

Messages in NIM SDK can be divided into two categories: session messages and system notification messages.

In-session messages

Session messages can only appear and be displayed in the chat interface. Generally, one user sends messages are to another user in the app (or group/chat room). For example, text messages and image messages belong to session messages. Session messages supported by the IM SDK include the following types:

In-session message type Description
Text message Messages that contain only texts.
Image message Image messages that contain information about image URLs, dimensions, and size.
Audio messages Audio messages that contain information about audio URLs, duration, size, and format.
Video messages Video messages that contain information about video URLs, duration, size, and format.
File message File messages that contain information about file URLs, size, and format. File formats are not restricted.
Location message Location messages that contain the geographic location title, longitude, and latitude.
Event notification Notifications are sent for events of groups, chat rooms and supergroups. Notifications of this type are sent by the server, and clients cannot send notification messages. Notification messages are sent in online, offline and roaming modes. Notification bar reminders are not supported
Tip message Tip messages cannot be delivered as push notifications and alerts shown on the notification bar. Instead, tip messages can serve as in-session notification reminders, such as the welcome message that appears when joining a session, or the prompt message after hitting a sensitive word during the session.
Custom message User-defined message type, such as red packets and rock paper scissors.

System notifications

System notifications are system-level messages. In general, system messages are sent by the system to specific users or groups. System notification messages include built-in and custom types.

  • The built-in system notifications belong to the types of notifications predefined by the SDK. The notification messages delivered by the CommsEase server to users are used for system event notifications. Notifications of group changes, such as group join requests, group invitation and more. If the apps also manage friend relationships, notifications for adding and deleting friends also belong to this type. System notifications are received and stored by the SDK, and provide simpler unread management. System notifications are online and offline messages that are not roaming or delivered using the push service.
  • Custom system notifications are some event status notifications you can use. The client and server can send custom system notifications. The SDK does not store or parse these notifications but only transmit and notify these events. The upper layer of your app can handle the persistence of custom notifications.
Type Storage Unread count Offline message Roaming message Message push
Built-in system notifications Supported Supported Supported Not supported Not supported
Custom System Notifications Not Supported Not Supported Supported Not Supported Supported

System notification development guides for each platform:

Concepts

Notifications and system notifications

  • concept

Notification messages are in-session messages that are delivered for online, offline, and roaming users. Notification messages are used for group notification events, not counted as unread messages. Notification messages cannot be delivered using the push service and shown as alert on the notification bar.

The built-in system notifications belong to the types of notifications predefined by CommsEase. The notification messages delivered by the CommsEase server to users are used for system event notifications. Notifications of group changes, such as group join requests, group invitation and more. If your apps also manage friend relationships, notifications for adding and deleting friends also belong to this type. System notifications are received and stored by the SDK, and provide simpler unread management. System notifications are sent as online and offline messages that are not roaming. Push service and alerts on the notification bar are unsupported for system notifications. You can use custom system notifications if you want to deliver the notification using the push service..

  • Scenarios

Notification messages are located in the middle of the chat interface. For example: group name update, XX ledt the group chat.

System notifications are displayed in the verification message list. For example: XX requested to add you as a friend.

Custom messages and custom system notifications

  • concept

The custom messages are in-session messages that are delivered for online, offline, and roaming users with alerts on the notification bar. Custom notifications are sent as online and offline messages. Roaming is not supported.

Custom messages belongs to the messaging system of CommsEase, stored in the message database by the SDK, and displayed to users together with other built-in message types. Custom notifications are used for some event status notifications. CommsEase does not store or parse these notifications. The SDK transmits and notifies these events only.

  • Scenarios

Custom messages are the same as text and voice messages, and are located on the left and right sides of the chat interface. For example, guessing games, stickers, and disappearing messages are implemented with custom messages.

A typical scenario for custom system notifications is the "typing indicator" displayed in the P2P chat interface.

Messaging

In addition to rich message types, IM SDK also provides with support for common messages.

Messaging Description
Offline messages Messages sent from others when a user is offline. Upon the next login, the offline messages temporarily stored during the offline period will be automatically delivered to the client SDK. In the private chat scenario, the most recent 5,000 offline messages in the last 30 days are loaded, and each session can load up to 100 recent offline messages; in the group chat scenario, the offline messages in the most recent 30 days are loaded, and each group chat session can load up to 100 recent offline messages.
Roaming Messages Automatically synchronize the roaming messages stored on the server when a new device logs in. The last 100 sessions within 7 days are synced, the last 100 messages per session are roamed
Multi-device sync When the same account logs in on multiple device at the same time, messages are sent to other devices in real time
Message history Supports local message history and cloud-based message history. The standard version allows you to obtain the cloud history messages last year, which can be extended to 3 years at most (add-on feature)
Message recall Recall delivered messages. Messages delivered within 2 minutes can be recalled by default. The duration can be configured in the CommsEase console. You can only recall messages in P2P chat and group chats. Messages delivered in chat rooms cannot be recalled.
Read receipt Indicate thel read and unread state of messages in group chat and P2P conversations
Message forwarding Forward one or more messages to other users or groups
@mention Use the custom field to implement the @mention operation. When sending a group message by @mentioning someone, it can be delivered with a list of @mentioned accounts in the extension field.
If a group member receives a message, check whether the member is included in the list of @mentioned accounts in the extension field. If included, a reminder of being @mentioned will be indicated on the interface.
Typing indicator Implement typing indicator using custom system notifications. For more information, see [Send custom system notifications](/en/docs/TM5MzM5Njk/jU1MTk5MzE?#custom system notifications)

Recent sessions

Recent sessions or the list of recent contacts. The session contains information, such as contact account, contact type, time of the last message, message status, message body, number of unread messages and more.

The SDK manages the recent session list and provides interfaces for querying and monitoring changes. If a chat with a specific user or group is updated by sending or receiving a message, the SDK will automatically update the recent session list and notify the upper layer. You do not need to update the list manually.

In some cases, you may want to manually insert a session in the recent contacts. For example, after creating an advanced group, the group needs to be displayed in the recent session list. Since no message is received when the advanced group is created, the SDK will not immediately update the recent session list. To meet the requirements at this time, you can insert a local message in the callback triggered when an advanced group is created. This can add the new group to the recent session list.

Note that recent sessions are stored locally and will not be roamed. After a new device logs in, the recent sessions list will be automatically generated based on the current roaming messages and offline messages.

Was this page helpful?
Yes
No
  • Message types
  • In-session messages
  • System notifications
  • Concepts
  • Notifications and system notifications
  • Custom messages and custom system notifications
  • Messaging
  • Recent sessions