Message Types Overview
The IM service offers a rich set of predefined message types (or "built-in message types") to simplify the development of instant messaging applications and enhance development efficiency.
A predefined message type (or "built-in message type") has a unique type identifier (ObjectName), and the message content must conform to the predefined content structure. Different message types have different processing logic on the server and client sides.
Message Attributes
Different message types have different processing logic on the server and client sides, specifically reflected in attributes such as whether the message is stored, whether it is counted as unread, whether it supports offline messages, and whether it supports push notifications.
- Client Counting and Storage Policies: The counting policy determines whether the message affects the unread message count. If a received message affects the unread count of a conversation, the unread message count of the conversation in the conversation list will increase by one. The storage policy determines whether the message is stored in the client's local database after being sent or received.
- Offline Message Caching: The IM server caches messages in one-to-one chats, group chats, and system conversations when the recipient is offline, with a default maximum caching period of 7 days. If the recipient comes online within 7 days, they can still receive the message. After 7 days, the message is removed from the offline cache.
- Remote Push Notifications: When the recipient is offline, whether the message triggers a remote push notification by default. A necessary condition for supporting remote push notifications is that the message has a push notification title and content. The IM service predefines push notification titles and content for some commonly used message types. Unless explicitly stated that push is not supported, other message types can trigger remote push notifications when the recipient is offline if the push notification title and content are set when sending the message.
Important
- The counting behavior on the client side only affects the unread count of the conversation, not the unread count displayed on the App badge.
- When sending one-to-one chat, group chat, chatroom, ultra group, or system messages via the server API, they are only stored in the recipient's server-side historical message records by default, and this behavior depends on the corresponding cloud storage service. If the cloud storage service is unavailable, the message cannot be stored in the historical records. If you need to store the message in the sender's server-side historical message records as well, please refer to How to Sync Sent Messages to the Sender Client.
- Ultra group and chatroom services do not support offline message caching.
- Web and mini-program clients do not support client-side message storage due to unreliable local storage.
- Since Web, mini-program, and PC clients do not have push service platforms, they cannot receive push notifications.
Message Classification
For easier understanding, we categorize the predefined message types into the following groups:
- User Content Messages: These include messages that users may send to each other, such as text, images, GIFs, voice, files, short videos, locations, references, and merged forwards.
- Notification Messages: These represent notification information that may need to be displayed in the chat UI, such as tip notifications.
- Status Messages: These represent states, such as typing status (indicating "the other party is typing") or read receipts in one-to-one chats.
- Signaling Messages: These are used by the IM service to implement its own business functions, and applications generally do not need to process them.
Each category provides multiple predefined message types. If the client SDK sends a predefined message type, you can directly construct the message object, set the corresponding message content, and send it. If using the server API, you need to specify the ObjectName of the message type and strictly follow the predefined message content structure when passing the message content.
User Content Messages
User content messages include messages that users may send to each other, such as text, images, GIFs, voice, files, short videos, locations, references, and merged forwards.
The IM server predefines push notification titles and content for user content message types. If custom push notification titles and content are not provided when sending the message, the predefined titles and content are used by default. The default push notification titles and content can be found in the documentation for each message type in the table below.
| Message Type | ObjectName | Client Counting and Storage Policy | Offline Message Caching | Remote Push Notification |
|---|---|---|---|---|
| Text Message | RC:TxtMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| High-Quality Voice Message | RC:HQVCMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Image Message | RC:ImgMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| GIF Message | RC:GIFMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Image and Text Message | RC:ImgTextMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| File Message | RC:FileMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Location Message | RC:LBSMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Short Video Message | RC:SightMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Reference Message | RC:ReferenceMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
| Merged Forward Message | RC:CombineMsg | ISCOUNTED: Stored on the client and counted as unread | Supported | Push supported by default |
Notification Messages
Notification messages generally need to be displayed in the chat UI, such as "Zhang San joined the group." These messages do not increase the unread message count.
The IM server does not predefine push notification titles and content for notification message types. If custom push notification titles and content are not provided when sending the message, remote push notifications will not be triggered by default, even if the recipient is offline. To support push notifications, please provide custom push notification content.
| Message Type | ObjectName | Client Counting and Storage Policy | Offline Message Caching | Remote Push Notification |
|---|---|---|---|---|
| Recall Notification Message | RC:RCNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
| Contact (Friend) Notification Message | RC:ContactNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
| Profile Notification Message | RC:ProfileNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
| Tip Notification Message | RC:InfoNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
| Group Notification Message | RC:GrpNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
| Command Reminder Message | RC:CmdNtf | ISPERSISTED: Stored on the client, not counted as unread | Supported | Push not supported by default |
Status Messages and Attributes
These represent real-time states, such as typing status, and can only be received when the user is online. Since status messages are not stored on the client or server, if the recipient is offline, they cannot receive the status message. If using the IM server API to send status messages, please use the appropriate interfaces: Send One-to-One Status Message, Send Group Status Message.
| Message Type | ObjectName | Client Counting and Storage Policy | Supports Offline Message Caching | Remote Push Notification |
|---|---|---|---|---|
| Typing Status Message | RC:TypSts | STATUS: Not stored on the client, not counted as unread | Not supported | Push not supported |
Signaling Messages
These are used by the IM service to implement SDK business functions. They are generally sent internally by the SDK or the IM server, and developers do not need to process them.
These are messages that need to be ensured to be received but do not need to be displayed, such as command information sent by the operation platform to the terminal. If the message recipient is offline, they can receive the message via offline messages when they come back online. Post-messaging Callback data will include these message types. Pre-messaging Callback services support configuring these message types.
Signaling Messages
The IM server predefines push notification titles and content for some signaling message types. If custom push notification titles and content are not provided when sending the message, the predefined titles and content are used by default.
| Message Type | ObjectName | Client Counting and Storage Policy | Supports Offline Message Caching | Remote Push Notification |
|---|---|---|---|---|
| Command Message | RC:CmdMsg | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
| Recall Command Message | RC:RcCmd | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| One-to-One Chat Read Receipt Message | RC:ReadNtf | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
| Group Chat Read Receipt Request Message | RC:RRReqMsg | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
| Group Chat Read Receipt Response Message | RC:RRRspMsg | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
| Multi-Device Read Status Sync Message | RC:SRSMsg | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
| Chatroom Attribute Notification Message | RC:chrmKVNotiMsg | NONE: Not stored on the client, not counted as unread | Supported | Push not supported by default |
RTC Signaling Messages
The IM server predefines push notification titles and content for RTC signaling message types. If custom push notification titles and content are not provided when sending the message, the predefined titles and content are used by default.
| Message Type | ObjectName | Client Counting and Storage Policy | Supports Offline Message Caching | Remote Push Notification |
|---|---|---|---|---|
| RTC Accept Signaling Message | RC:VCAccept | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| RTC Hangup Signaling Message | RC:VCHangup | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| RTC Invite Signaling Message | RC:VCInvite | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| RTC Media Switch Signaling Message | RC:VCModifyMedia | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| RTC Member Change Signaling Message | RC:VCModifyMem | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
| RTC Ringing Signaling Message | RC:VCRinging | NONE: Not stored on the client, not counted as unread | Supported | Push supported by default |
Message Extension Function Messages
The ObjectName for message extension function messages is RC:MsgExMsg. In ultra group message services, when setting or deleting message extension information, you can receive message extension function messages via message callbacks or post-messaging callbacks. Clients cannot receive these messages.