Sending Messages
This document describes how to use the IMLib SDK to send messages in one-to-one chats, group chats, and chatroom conversations.
- For sending ultra group messages, refer to the ultra group documentation Sending and Receiving Messages.
- By default, RC allows users not in a chatroom to send messages within it. If you want to prevent users not in a chatroom from sending messages via client SDKs, go to the [RC Console] under Chat > Chat settings > Chatroom, and enable the SDK users not in chatroom cannot send messages feature. Note: Server-side chatroom message sending APIs are not affected by this configuration.
Introduction to Message Content Types
The content property of the [Message] object defined by the IMLib SDK can contain two main types of message content: regular message content and media message content. The parent class for regular message content is [MessageContent], while the parent class for media message content is [MediaMessageContent]. The key difference between sending media messages and regular messages lies in whether there is a data upload process.
| Feature | Message Content Type | Parent Class | Description |
|---|---|---|---|
| Text Message | [TextMessage] | MessageContent | Content of text messages. |
| Quote Reply | [ReferenceMessage] | MessageContent | Content of quoted messages, used to implement quote reply functionality. |
| Image Message | [ImageMessage] | MediaMessageContent | Content of image messages, supporting sending original images. |
| GIF Message | [GIFMessage] | MediaMessageContent | Content of GIF messages. |
| File Message | [FileMessage] | MediaMessageContent | Content of file messages. |
| Voice Message | [HQVoiceMessage] | MediaMessageContent | Content of high-quality voice messages. |
| Mentions (@) | N/A | N/A | @ mentions are not a predefined message type. See How to Send @ Messages. |
The above are some of the built-in message content types in the IMLib SDK. You can also create custom message content types and send them using the sendMessage or sendMediaMessage methods. For details, see Custom Message Types.
Important
- Use the
sendMessagemethod for regular messages andsendMediaMessagefor media messages.- The client SDK has a rate limit of 5 messages per second.
This document uses the message-sending methods from the IMLib SDK core class [RongCoreClient] (or [RongIMClient]).
Regular Messages
Regular messages refer to text messages, quoted messages, etc., that do not involve media file uploads. The message content for regular messages is a subclass of MessageContent, such as text message content ([TextMessage]) or custom regular message content.
Constructing Regular Messages
Before sending, you need to construct a [Message] object. The [conversationType] field specifies the conversation type, and targetId represents the target ID of the conversation. The example below constructs a message object containing text message content ([TextMessage]).
String targetId = "Target ID";
ConversationType conversationType = Conversation.ConversationType.PRIVATE;
TextMessage messageContent = TextMessage.obtain("Message content");
Message message = Message.obtain(targetId, conversationType, messageContent);
Sending Regular Messages
If the [Message] object contains regular message content, use the sendMessage method of the IMLib SDK core class [RongCoreClient] (or [RongIMClient]) to send the message.
String pushContent = null;
String pushData = null;
RongCoreClient.getInstance().sendMessage(message, pushContent, pushData, new IRongCoreCallback.ISendMessageCallback() {
@Override
public void onAttached(Message message) {
}
@Override
public void onSuccess(Message message) {
}
@Override
public void onError(Message message, IRongCoreEnum.CoreErrorCode coreErrorCode) {
}
});
The [sendMessage] method directly provides parameters for controlling push notification content (pushContent) and push additional information (pushData). Alternatively, you can use the [MessagePushConfig] for push notification configuration, which includes pushContent and pushData and offers more push notification capabilities, such as titles, content, icons, or other third-party vendor-specific configurations. For details, see Remote Notifications.
Regarding whether to configure pushContent in the input parameters or the messagePushConfig property of Message, refer to the following:
- If the message type is a [predefined message type] of the [IM Service] under [user content message formats], such as [TextMessage],
pushContentcan be set tonull. When the message triggers an offline push notification, the remote push notification will use the server's predefined content by default. For default push notification content for each message type, see [User Content Message Formats]. - If the message type is a notification or signaling type (excluding "recall command messages") under [predefined message types] of the [IM Service] and requires remote push notification support,
pushContentmust be filled in; otherwise, recipients will not receive remote push notifications when offline. If remote push is not needed, this field can be left blank. - If the message type is a custom message type, refer to How to Support Remote Push for Custom Messages.
- Note that chatroom conversations do not support offline message mechanisms and thus do not support offline message-to-push conversion.
| Parameter | Type | Description |
|---|---|---|
| message | [Message] | The message body to send. Required properties include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the Message structure, see [Message Introduction]. |
| pushContent | String | Modifies or specifies the content displayed in the remote push notification bar. You can also configure this in the MessagePushConfig of Message, which will override this setting. For details, see Remote Notifications. |
| pushData | String | Additional information for remote push. When the recipient receives the remote push message, this field can be retrieved via:
MessagePushConfig of Message, which will override this setting. For details, see Remote Notifications. |
| callback | [ISendMessageCallback] | Callback for sending the message. |
Through the callback handler [ISendMessageCallback] of the sendMessage method in RongCoreClient, the RC server will always notify you whether the message was sent successfully. If sending fails due to any issue, the exception can be returned via the callback method.
- For how to customize offline remote push notifications for recipients, see Remote Notifications.
- Custom message types do not support offline message-to-push by default. To enable support, see How to Support Remote Push for Custom Messages.
Media Messages
Media messages refer to images, GIFs, files, etc., that require media file upload processing. The message content type for media messages is a subclass of MeidaMessageContent, such as high-quality voice message content ([HQVoiceMessage]) or your custom media message content.
Constructing Media Messages
Before sending, you need to construct a [Message] object. The content field of the media message Message object must be a subclass object of [MediaMessageContent], representing media message content. Examples include image message content ([ImageMessage]), GIF message content ([GIFMessage]), or custom media message content inheriting from [MediaMessageContent].
Image message content ([ImageMessage]) supports sending original images.
String targetId = "Target ID";
ConversationType conversationType = Conversation.ConversationType.ULTRA_GROUP;
Uri localUri = Uri.parse("file://path_to_image");//Local path of the image; recipients can get the auto-generated thumbnail Uri via getThumUri
boolean mIsFull = true; //Whether to send the original image
ImageMessage mediaMessageContent = ImageMessage.obtain(localUri, mIsFull);
Message message = Message.obtain(targetId, conversationType, mediaMessageContent);
Before sending, images are compressed in quality, and thumbnails are generated for display in the chat UI. GIFs do not have thumbnails and are not compressed.
- Image Message Thumbnails: The SDK generates a large image at 30% of the original quality that meets standard size requirements before uploading and sending. The compressed image's longest side does not exceed 240 px. The thumbnail is used for display in the chat UI.
- Images: If the original image is not selected for sending, the SDK generates a large image at 85% of the original quality that meets standard size requirements before uploading and sending. The compressed image's longest side does not exceed 1080 px.
Generally, it is not recommended to modify the SDK's default compression settings. To adjust the SDK's compression quality, refer to the knowledge base article How to Modify SDK Default Image and Video Compression Settings.
Sending Media Messages
Use the sendMediaMessage method to send media messages. The SDK generates thumbnails for images, short videos, etc., compresses them according to the default compression settings, uploads the media files to RC's default file server (file storage duration), and sends the message after successful upload. If an image message is set to send the original image, it will not be compressed.
String pushContent = null;
String pushData = null;
RongCoreClient.getInstance().sendMediaMessage(message, pushContent, pushData, new IRongCoreCallback.ISendMediaMessageCallback() {
@Override
public void onProgress(Message message, int i) {
}
@Override
public void onCanceled(Message message) {
}
@Override
public void onAttached(Message message) {
}
@Override
public void onSuccess(Message message) {
}
@Override
public void onError(final Message message, final IRongCoreEnum.CoreErrorCode coreErrorCode) {
}
});
The [sendMediaMessage] method directly provides parameters for controlling push notification content (pushContent) and push additional information (pushData). Alternatively, you can use the [MessagePushConfig] for push notification configuration, which includes pushContent and pushData and offers more push notification capabilities, such as titles, content, icons, or other third-party vendor-specific configurations. For details, see Remote Notifications.
Regarding whether to configure pushContent in the input parameters or the messagePushConfig property of Message, refer to the following:
- If the message type is a [predefined message type] of the [IM Service] under [user content message formats], such as [HQVoiceMessage],
pushContentcan be set tonull. When the message triggers an offline push notification, the remote push notification will use the server's predefined content by default. For default push notification content for each message type, see [User Content Message Formats]. - If the message type is a notification or signaling type (excluding "recall command messages") under [predefined message types] of the [IM Service] and requires remote push notification support,
pushContentmust be filled in; otherwise, recipients will not receive remote push notifications when offline. If remote push is not needed, this field can be left blank. - If the message type is a custom message type, refer to How to Support Remote Push for Custom Messages.
- Note that chatroom conversations do not support offline message mechanisms and thus do not support offline message-to-push conversion.
| Parameter | Type | Description |
|---|---|---|
| message | [Message] | The message body to send. Required properties include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the Message structure, see [Message Introduction]. |
| pushContent | String | Modifies or specifies the content displayed in the remote push notification bar. You can also configure this in the MessagePushConfig of Message, which will override this setting. For details, see Remote Notifications. |
| pushData | String | Additional information for remote push. When the recipient receives the remote push message, this field can be retrieved via:
MessagePushConfig of Message, which will override this setting. For details, see Remote Notifications. |
| callback | [ISendMediaMessageCallback] | Callback for sending the media message. |
Through the callback handler [ISendMediaMessageCallback] of the sendMediaMessage method in RongCoreClient, the RC server will always notify you of the media file upload progress and whether the message was sent successfully. If sending fails due to any issue, the exception can be returned via the callback method.
By default, the media message sending method uploads media files to RC's file server, and you can download media message files in the client application. RC imposes size limits on uploaded media files: GIFs are limited to 2 MB, and files are limited to 100 MB. If you need to increase the GIF size limit, [submit a ticket], but the file upload limit cannot be adjusted.
- For how to customize offline remote push notifications for recipients, see Remote Notifications.
- Custom message types do not support offline message-to-push by default. To enable support, see How to Support Remote Push for Custom Messages.
Sending Media Messages and Uploading to Your Own Server
You can directly send files hosted on your server. Pass the URL (indicating its location) of the media file as a parameter when constructing the media message content. In this case, your file will not be hosted on RC's servers. When sending file messages with remote URLs, there are no file size restrictions, and you can directly use the sendMessage method to send the message.
If you want the SDK to send the message after you have successfully uploaded it, you can use the sendMediaMessage method. Implement the media file upload yourself in the onAttached callback method of the [ISendMediaMessageCallbackWithUploader] interface, and notify the SDK after the upload is successful by providing the remote address of the media file. The SDK will send the message upon receiving the upload success notification.
String path = "file://path_to_image";
Uri localUri = Uri.parse(path);
ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "Target ID";
ImageMessage imageMessage = ImageMessage.obtain(localUri, localUri);
Message message = Message.obtain(targetId, conversationType, imageMessage);
IRongCoreCallback.ISendMediaMessageCallbackWithUploader sendMediaMessageCallbackWithUploader =
new IRongCoreCallback.ISendMediaMessageCallbackWithUploader() {
@Override
public void onAttached(
Message message, IRongCoreCallback.MediaMessageUploader uploader) {
/*Upload image to your own server*/
uploadImg(imgMsg.getPicFilePath(), new UploadListener() {
@Override
public void onSuccess(String url) {
// Upload successful, call the SDK's success method and pass back the remote address of the image
uploader.success(Uri.parse(url));
}
@Override
public void onProgress(float progress) {
// Update upload progress
uploader.update((int) progress);
}
@Override
public void onFail() {
// Image upload failed, call the error method.
uploader.error();
}
});
}
@Override
public void onError(
final Message message, final IRongCoreEnum.CoreErrorCode coreErrorCode) {
// Sending failed
}
@Override
public void onProgress(Message message, int progress) {
// Sending progress
}
@Override
public void onSuccess(Message message) {
// Sending successful
}
@Override
public void onCanceled(Message message) {
// Sending canceled
}
};
RongCoreClient.getInstance().sendMediaMessage(
message, pushContent, pushData, sendMediaMessageCallbackWithUploader);
## How to Send @ Messages \{#mentionedinfo}
@ messages are not a predefined message type in RC's IM service (see the server-side documentation [Message Type Overview]). RC helps apps implement the mention (@) functionality by carrying `mentionedInfo` data in messages.
The [MentionedInfo] field in the message's `MessageContent` stores information about the mentioned users. Both SDK built-in message types and custom message types directly or indirectly inherit from the [MessageContent] class.
RC supports adding `mentionedInfo` to messages sent to groups and ultra groups. Before sending a message, you can construct `MentionedInfo` and set it in the message's `MessageContent`.
```java
List<String> userIdList = new ArrayList<>();
userIdList.add("userId1");
userIdList.add("userId2");
MentionedInfo mentionedInfo = new MentionedInfo(MentionedInfo.MentionedType.PART, userIdList, null);
TextMessage messageContent = TextMessage.obtain("Text message");
messageContent.setMentionedInfo(mentionedInfo);
`MentionedInfo` parameters:
| Parameter | Type | Description |
|:-------------------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | MentionedType | (Required) Specifies the type of `MentionedInfo`. `MentionedType.ALL` indicates that everyone needs to be mentioned (@). `MentionedType.PART` indicates that only specific users need to be mentioned, and the mentioned users must be specified in `userIdList`. |
| userIdList | List\<String\> | A collection of user IDs to be mentioned (@). Required when `type` is `MentionedType.PART`; starting from version 5.3.1, it also supports mentioning specific users when `type` is `MentionedType.ALL`. The receiving end can obtain `userIdList` data via `mentionedInfo`. |
| mentionedContent | String | The content displayed in the notification bar when triggering offline push notifications. If `NULL`, the default prompt ("Someone mentioned you") is displayed. The `mentionedContent` in @ messages has the highest priority and will override all default or custom `pushContent` data. |
The following example demonstrates sending a text message mentioning specific users to a group chat session.
```java
List<String> userIdList = new ArrayList<>();
userIdList.add("userId1");
userIdList.add("userId2");
MentionedInfo mentionedInfo = new MentionedInfo(MentionedInfo.MentionedType.PART, userIdList, null);
TextMessage messageContent = TextMessage.obtain("Text message");
messageContent.setMentionedInfo(mentionedInfo);
Message message = Message.obtain(mTargetId, ConversationType.GROUP, messageContent);
RongCoreClient.getInstance().sendMessage(message, null , null, new IRongCoreCallback.ISendMessageCallback(){
/**
* Callback before message is sent, when the message has already been stored in the database
* @param message The message stored in the database
*/
@Override
public void onAttached(Message message) {
}
/**
* Message sent successfully.
* @param message The message after successful sending
*/
@Override
public void onSuccess(Message message) {
}
/**
* Message sending failed
* @param message The message that failed to send
* @param errorCode Specific error
*/
@Override
public void onError(Message message, IRongCoreEnum.CoreErrorCode coreErrorCode) {
}
});
After receiving the message, the IMLib SDK needs to process the @ message data. You can obtain the `MentionedInfo` object carried by the message object via the following method after retrieving the `Message` (message object).
```java
MentionedInfo mentionedInfo = message.getContent().getMentionedInfo();
## Remote Notifications
:::tip
Chatroom sessions do not support offline message mechanisms and therefore do not support offline message-to-push.
If your app has configured third-party push notifications with RC, when the message recipient is offline, the RC server will determine whether to trigger a remote push based on the message type, the recipient's supported push channels, and the recipient's Do Not Disturb settings.
Remote push notifications are typically displayed in the system's notification bar. RC's built-in message types will display the notification title and content in the notification bar by default. For the default push notification content of each message type, see [User Content Message Formats].
If you need personalized offline push notifications, you can modify or specify the remote push notification title, content, and other attributes in the following ways:
-
The input parameters of the [sendMessage] and [sendMediaMessage] methods directly provide the
pushContentparameter for controlling push notification content. -
If you need to control more attributes of offline push notifications, such as the title, content, icon, or personalized configurations based on third-party vendor channels, use the
setMessagePushConfigmethod of [Message] to configure them. ThepushContentconfiguration in the message push attributes will override thepushContentin the message-sending interface.
Configuring Message Push Attributes
When sending a message, you can personalize the push behavior of a single message by setting the [MessagePushConfig] object. For example:
-
Customize the push title and push notification content
-
Customize the notification bar icon
-
Add remote push additional information
-
Bypass the recipient client's configuration and force the display of notification content in the push notification
-
Other personalized configurations supported by APNs or Android push channels
Compared to the pushContent and pushData in the message-sending method's input parameters, the configurations in MessagePushConfig have higher priority. When sending a message, if MessagePushConfig is configured, the configurations in MessagePushConfig will be used first.
Message message = Message.obtain(mTargetId, mConversationType, textMessage);
MessagePushConfig messagePushConfig = new MessagePushConfig.Builder().setPushTitle(title)
.setPushContent(content)
.setPushData(data)
.setForceShowDetailContent(forceDetail)
.setAndroidConfig(new AndroidConfig.Builder()
.setNotificationId(id)
.setChannelIdHW(hw)
.setCategoryHW("IM")
.setChannelIdMi(mi)
.setChannelIdOPPO(oppo)
.setTypeVivo(vivo ? AndroidConfig.SYSTEM : AndroidConfig.OPERATE)
.setCategoryVivo("IM")
.build())
.setIOSConfig(new IOSConfig(threadId, apnsId)).setTemplateId("")
build();
message.setMessagePushConfig(messagePushConfig);
// Call the corresponding sending method based on the message type
`MessagePushConfig` attribute descriptions:
| Parameter | Type | Description |
|:-------------------------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| disablePushTitle | boolean | Whether to block the notification title. This attribute is only valid for iOS platform target users. The notification title is mandatory for Android third-party push platforms, so it is not currently supported. |
| pushTitle | String | Push title. The push title specified here has the highest priority. If not set, refer to the default **push notification title** and **push notification content** descriptions for built-in message types in [User Content Message Formats]. |
| pushContent | String | Push content. The push content specified here has the highest priority. If not set, refer to the default **push notification title** and **push notification content** descriptions for built-in message types in [User Content Message Formats]. |
| pushData | String | Remote push additional information. If not set, the `pushData` value set in the message-sending parameters will be used. When the recipient receives the remote push notification, the content of this field can be obtained via the following method: `io.rong.push.notification.PushNotificationMessage#getPushData()`. |
| forceShowDetailContent | boolean | Whether to bypass the recipient client's configuration and force the display of notification content (`pushContent`) in the push notification.<br/><br/>Client devices can use `setPushContentShowStatus` to set the push notification to display only reminders like "You have received a notification." When sending a message, you can set `forceShowDetailContent` to 1 to bypass this configuration and force the recipient client to display the push content in the push notification for this message. |
| iOSConfig | IOSConfig | iOS platform push notification configuration. Applies when the target device is an iOS platform device. For detailed descriptions, see **`iOSConfig` Attribute Descriptions**. |
| androidConfig | AndroidConfig | Android platform push notification configuration. Applies when the target device is an Android platform device. For detailed descriptions, see **`AndroidConfig` Attribute Descriptions**. |
| templateId | String | Push template ID. Matches the language content set in the template corresponding to the template ID based on the language environment set by the target client user via `RongIMClient`'s `setPushLanguageCode`. If no match is found, the default content is used for push notifications.<br/><br/>Template content is set in **Console** > **Custom Push Copy**. For specific operations, see [Configuring and Using Custom Multi-Language Push Templates](https://help.rongcloud.cn/t/topic/1030). |
- `iOSConfig` attribute descriptions
| Parameter | Type | Description |
|:------------------|:-------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| threadId | String | iOS platform notification grouping ID. Notifications with the same `threadId` will be grouped together (supported since iOS 10). |
| apnsCollapseId | String | iOS platform notification replacement ID. When `apnsCollapseId` is the same, newly received notifications will replace old ones (max 64 bytes, supported since iOS 10). |
| richMediaUri | String | Custom notification icon URL for iOS push notifications (displayed on the right side). Apps need to parse `richMediaUri` and implement the display. Image requirements: 120 * 120px, PNG or JPG format. Supported since SDK version 5.2.4. |
| interruptionLevel | String | Applies to iOS 15 and later systems. Values can be `passive`, `active` (default), `time-sensitive`, or `critical`. For details, refer to [APNs interruption-level](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc). In iOS 15 and later, system features like "Scheduled Summary" and "Focus Mode" may prevent important push notifications (e.g., balance changes) from being noticed promptly. Consider setting this field. Supported since SDK version 5.6.7. |
- `AndroidConfig` attribute descriptions
| Parameter | Type | Description |
|:----------------|:-------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| notificationId | String | Android platform push unique identifier. Currently supported for Xiaomi and Huawei push platforms. By default, developers don't need to set this - when a message generates a push, the message's `messageUId` is used as the `notificationId`. |
| channelIdMi | String | Xiaomi push notification channel ID. For usage and creation methods, refer to third-party documentation [Xiaomi Push Message Classification Rules](https://dev.mi.com/console/doc/detail?pId=2422#_4). |
| imageUrlMi | String | (**This field is no longer functional as Xiaomi has discontinued support for this capability**) URL of the notification image used for Xiaomi notification-type pushes. Image requirements: 120 * 120px, PNG or JPG format.<br />Supported since version 5.1.7. Works with MIUI China edition (requires MIUI 12+) and international edition. |
| channelIdHW | String | Huawei push notification channel ID. For usage and creation methods, refer to third-party documentation [Huawei Custom Notification Channels](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/android-custom-chan-0000001050040122). For more about notification channels, see [Android official documentation](https://developer.android.com/training/notify-user/channels). |
| imageUrlHW | String | URL for the custom small notification icon (displayed on the right side) in Huawei push notifications. If not set, no icon will be shown. File must be smaller than 512 KB. Recommended size: 40dp x 40dp with 8dp rounded corners. Icons exceeding recommended size may be compressed or incompletely displayed.<br />Supported since version 5.1.7. |
| importanceHW | String | Huawei push notification priority level. `LOW` means silent notification (no sound/vibration when message arrives). `NORMAL` (default) means strong notification (with sound/vibration). Actual notification behavior depends on `categoryHW` value, Console `category` configuration, or [Huawei Smart Classification] results. Supported since SDK version 5.1.3. |
| categoryHW | String | Huawei push channel message self-classification identifier, empty by default. Must be uppercase letters (e.g., `IM`). App must complete [Huawei Self-Classification Application] or [Special Permission Application] per Huawei requirements for this field to take effect. See Huawei documentation [Huawei Message Classification Standards]. This field has higher priority than the Huawei push Category configured in Console under App Key's **Application Identifier**. Supported since SDK version 5.4.0. |
| imageUrlHonor | String | URL for custom large notification icon (displayed on the right side) in Honor push notifications. If not set, no icon will be shown. File must be smaller than 512 KB. Recommended size: 40dp x 40dp with 8dp rounded corners. Icons exceeding recommended size may be compressed or incompletely displayed. Supported since SDK version 5.6.7. |
| importanceHonor | String | Honor push Android notification category, determining device notification behavior. `LOW` means marketing/informational messages. `NORMAL` (default) means service/communication messages. Supported since SDK version 5.6.7. |
| typeVivo | String | VIVO push service message type. Options: `0` (operational messages) and `1` (system messages). Corresponds to VIVO's `classification` field. See [VIVO Push Message Classification]. |
| categoryVivo | String | VIVO push service message sub-category (e.g., `IM` for instant messages). Corresponds to VIVO's `category` field. For valid values, see [VIVO Push Message Classification]. If specifying `categoryVivo`, must also specify `typeVivo` (system or operational message). Ensure sub-category complies with VIVO's allowed content for system/operational messages. `categoryVivo` has higher priority than VIVO push Category configured in Console under App Key's **Application Identifier**. Supported since SDK version 5.4.2. |
| channelIdOPPO | String | OPPO push notification channel ID. For usage and creation methods, refer to third-party documentation [OPPO PUSH Channel Upgrade Instructions](https://open.oppomobile.com/new/developmentDoc/info?id=11227). |
| channelIdFCM | String | FCM push notification channel ID. App must create a channel with this ID before receiving any notifications with this channel ID. See [Android official documentation](https://developer.android.com/guide/topics/ui/notifiers/notifications?hl=zh-cn#ManageChannels). |
| collapseKeyFCM | String | FCM push notification group ID. Supported since SDK version 5.1.3. **Note**: When using this field, ensure FCM push configuration in Console uses **Notification Message** method. |
| imageUrlFCM | String | FCM push notification icon URL (displayed on the right side). If not set, no icon will be shown. Supported since SDK version 5.1.3. **Note**: When using this field, ensure FCM push configuration in Console uses **Certificate** authentication and **Notification Message** method. |
### How Custom Messages Support Remote Push Notifications
RC provides default remote notification titles and content for built-in message types (see [User Content Message Formats]). However, if you're sending custom message types, you need to provide the `pushContent` field yourself; otherwise, users won't receive offline push notifications. Details:
- For custom message types that require offline push notifications, you must provide the `pushContent` field to RC, otherwise users won't receive offline push notifications.
- For custom message types that don't require remote push notifications (e.g., app-level operation commands implemented via custom messages), you can leave the `pushContent` field empty.
:::tip
To enable offline push notification capability for custom messages, you must provide `pushContent` field content to RC either through message parameters or push attributes. Otherwise, recipients won't receive offline push notifications.
:::
### Disabling Push Notifications for Messages
When the recipient is offline, the RC server by default triggers the push service to deliver messages through the push channel (whether the server triggers push notifications is also affected by application-level and user-level Do Not Disturb settings).
Your app users may wish to specify that a particular message should not trigger push notifications when sent. This requirement can be achieved by configuring the `MessageConfig` of the `Message` object.
In the following example, we set the `disableNotification` of `messageConfig` to `true` to disable push notifications for this message. When the recipient comes back online, they will automatically receive one-to-one chat, group chat, and system conversation messages through RC's offline message cache (which retains messages for up to 7 days). Ultra group messages require active retrieval as they don't support offline messaging.
```java
String targetId = "Target ID";
ConversationType conversationType = ConversationType.PRIVATE;
TextMessage messageContent = TextMessage.obtain("Message content");
Message message = Message.obtain(targetId, conversationType, messageContent);
message.setMessageConfig(new MessageConfig.Builder().setDisableNotification(true).build());
## How to Transmit Custom Data
If your application needs to transmit custom data to the receiving end, you can implement it through the following methods:
- The additional information field in the message content [MessageContent], **which will be sent along with the instant message to the receiving end**. After receiving the message online, the recipient can obtain this field from the message content. Note this differs from `Message.extra`, which is a local operation field and won't be sent to the server.
- Remote push additional information `pushData`. You can directly set `pushData` in the input parameters of [sendMessage] and [sendMediaMessage], or use the field with the same name in the message push attributes - the latter will override the former. **`pushData` will only be delivered to the receiving device when the message triggers an offline remote push**. When the receiving end gets the remote push notification, they can obtain this field content through: `io.rong.push.notification.PushNotificationMessage#getPushData()`.
## How to Handle Message Sending Failures
For message types stored locally by the client (see [Message Type Overview]), if the (`onAttached`) callback is triggered, it means the message has been stored in the local database and entered the local message list.
- If storage fails, you can check whether the parameters are valid and whether device storage can be written normally.
- If storage succeeds but message sending fails (`onError`), the app can temporarily display this failed-to-send message in the UI and cache the `Message` instance thrown by `onError`, then call `sendMessage` / `sendMediaMessage` again at an appropriate time to resend. Note that if you don't reuse this message instance but resend a new message with the same content, the local message list will store two duplicate messages.
For messages not stored locally by the client, if sending fails (`onError`), the app can cache the message instance and retry sending, or directly create a new message instance to send.
## How to Implement Message Forwarding and Mass Messaging
**Forwarding messages**: The IMLib SDK doesn't provide a forwarding message interface. To implement message forwarding, apps can call the send message interface.
**Mass messaging**: Mass messaging refers to sending messages to multiple users. More precisely, it means sending messages to multiple Target IDs<sup><a href="/guides/glossary/imglossary#TargetID">?</a></sup>, where a Target ID may represent a user, a group, or a chatroom. The client SDK doesn't provide an API to directly implement mass messaging. You can consider the following implementation methods:
- The app can loop through calling the client's send message API. Note that the client SDK limits the message sending frequency to a maximum of 5 messages per second.
- The app can integrate the IM Server API on the business server side and have the app's business server handle mass messaging. The IM Server API's [Send Private Message] interface supports sending one-to-one messages to multiple users at once. You can also use the [Send Group Message] and [Send Chatroom Message] interfaces to send messages to multiple groups or chatrooms at once.