Sending Messages

This document describes how to use the IMLib SDK to send messages in one-to-one chats, group chats, and chatroom conversations.

tip

• By default, RC allows users not in a chatroom to send messages within it. If you wish to prevent users not in the chatroom from sending messages via the client SDK, you can enable the Users not in the chatroom cannot send messages via SDK feature in the Configuration > Chat settings > Basic features > Chatroom section of the [RC Console's Basic Features Page]. Note: This configuration does not affect the server-side API for sending chatroom messages.

Introduction to Message Content Types

The IMLib SDK defines two main types of message content in the content property of the [Message] object: regular message content and media message content. The parent class for regular message content is [MessageContent], and the parent class for media message content is [MediaMessageContent]. The key difference between sending media messages and regular messages is the presence of an upload process for media messages.

Feature	Message Content Type	Parent Class	Description
Text Message	[TextMessage]	MessageContent	The content of a text message.
Reference Reply	[ReferenceMessage]	MessageContent	The content of a reference message, used to implement the reference reply feature.
Image Message	[ImageMessage]	MediaMessageContent	The content of an image message, supporting the sending of original images.
GIF Message	[GIFMessage]	MediaMessageContent	The content of a GIF message.
File Message	[FileMessage]	MediaMessageContent	The content of a file message.
Voice Message	[HQVoiceMessage]	MediaMessageContent	The content of a high-quality voice message.
Mention Others (@ Message)	Not Applicable	Not Applicable	@ messages are not predefined message types. For details, 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 sendMessage method to send regular messages and the sendMediaMessage method to send media messages.
• The client SDK has a frequency limit for sending messages, allowing a maximum of 5 messages per second.

This document uses the core class [RongCoreClient] (or [RongIMClient]) of the IMLib SDK to send messages.

Regular Messages

Regular messages refer to text messages, reference messages, and other messages that do not involve media file uploads. Regular messages have message content that 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. The targetId represents the target ID of the conversation. The following example 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). Another way is to use the message push attribute configuration [MessagePushConfig], which includes pushContent and pushData, and provides more push notification configuration capabilities, such as title, content, icon, or other third-party vendor personalized configurations. For details, see Remote Push Notifications.

Regarding whether to configure the input parameters or the pushContent in the MessagePushConfig attribute of the Message, refer to the following:

• If the message type is a [predefined message type of the IM service] in the [user content class message format], such as [TextMessage], pushContent can be set to null. Once the message triggers an offline push notification, the remote push notification will use the preset push notification content on the server. For the default push notification content of each type of message, see [User Content Class Message Format].
• If the message type is a notification class or signaling class (excluding "recall command message") in the [predefined message type of the IM service], and remote push notification support is required, pushContent must be filled in; otherwise, the recipient will not receive the remote push notification 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 therefore do not support offline message to push conversion.

Parameter	Type	Description
message	[Message]	The message body to be sent. Required attributes include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the structure of Message, see [Message Introduction].
pushContent	String	Modify or specify the content displayed in the remote message push notification bar. You can also configure this in the push attributes (MessagePushConfig) of Message, which will override the configuration here. For details, see Remote Push Notifications.
pushData	String	Additional information for remote push. When the recipient receives a remote push message, they can obtain the content of this field via the following method: io.rong.push.notification.PushNotificationMessage#getPushData(). You can also configure this in the push attributes (MessagePushConfig) of Message, which will override the configuration here. For details, see Remote Push Notifications.
callback	[ISendMessageCallback]	Callback for sending messages.

Through the callback handler [ISendMessageCallback] of the RongCoreClient's sendMessage method, the RC server will always notify you whether your message has been sent successfully. If the message fails to send due to any issue, an exception will be returned via the callback method.

tip

• For how to personalize the remote push notification received by the recipient when offline, see Remote Push Notifications.
• Custom message types do not support the offline message to push mechanism by default. If support is needed, see How to Support Remote Push for Custom Messages.

Media Messages

Media messages refer to images, GIFs, files, and other messages that require media file upload processing. Media message content types are subclasses of MeidaMessageContent, such as high-quality voice message content ([HQVoiceMessage]), or your custom media message content types.

Constructing Media Messages

Before sending, you need to construct a [Message] object. The content field of the media message Message object must be passed a subclass object of [MediaMessageContent], representing media message content. For example, image message content ([ImageMessage]), GIF message content ([GIFMessage]), or custom media message content that inherits from [MediaMessageContent].

Image message content ([ImageMessage]) supports sending the original image.

String targetId = "Target ID";
ConversationType conversationType = Conversation.ConversationType.ULTRA_GROUP;

Uri localUri = Uri.parse("file://image path");//Local path of the image, the recipient can obtain the automatically 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, the image will be compressed in quality, and a thumbnail will be generated for display in the chat UI. GIFs do not have thumbnails and will not be compressed.

• Thumbnails for Image Messages: The SDK will generate a large image with 30% quality of the original image that meets the standard size requirements before uploading and sending. The longest side of the compressed image will 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 will generate a large image with 85% quality of the original image that meets the standard size requirements before uploading and sending. The longest side of the compressed image will not exceed 1080 px.

Generally, it is not recommended to modify the SDK's default compression configuration. If you need to adjust the SDK's compression quality, refer to the knowledge base document How to Modify the SDK's Default Image and Video Compression Configuration.

Sending Media Messages

To send media messages, use the sendMediaMessage method. The SDK will generate thumbnails for images, short videos, etc., compress them according to the default compression configuration, upload the images, short videos, and other media files to RC's default file server (file storage duration), and send the message after the upload is successful. If the 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). Another way is to use the message push attribute configuration [MessagePushConfig], which includes pushContent and pushData, and provides more push notification configuration capabilities, such as title, content, icon, or other third-party vendor personalized configurations. For details, see Remote Push Notifications.

Regarding whether to configure the input parameters or the pushContent in the MessagePushConfig attribute of the Message, refer to the following:

• If the message type is a [predefined message type of the IM service] in the [user content class message format], such as [HQVoiceMessage], pushContent can be set to null. Once the message triggers an offline push notification, the remote push notification will use the preset push notification content on the server. For the default push notification content of each type of message, see [User Content Class Message Format].
• If the message type is a notification class or signaling class (excluding "recall command message") in the [predefined message type of the IM service], and remote push notification support is required, pushContent must be filled in; otherwise, the recipient will not receive the remote push notification 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 therefore do not support offline message to push conversion.

Parameter	Type	Description
message	[Message]	The message body to be sent. Required attributes include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the structure of Message, see [Message Introduction].
pushContent	String	Modify or specify the content displayed in the remote message push notification bar. You can also configure this in the push attributes (MessagePushConfig) of Message, which will override the configuration here. For details, see Remote Push Notifications.
pushData	String	Additional information for remote push. When the recipient receives a remote push message, they can obtain the content of this field via the following method: io.rong.push.notification.PushNotificationMessage#getPushData(). You can also configure this in the push attributes (MessagePushConfig) of Message, which will override the configuration here. For details, see Remote Push Notifications.
callback	[ISendMediaMessageCallback]	Callback for sending media messages.

Through the callback handler [ISendMediaMessageCallback] of the RongCoreClient's sendMediaMessage method, the RC server will always notify you of the media file upload progress and whether your message has been sent successfully. If the message fails to send due to any issue, an exception will be returned via the callback method.

The method for sending media messages by default uploads media files to RC's file server. You can download media message files in the client application. RC has imposed limits on the size of uploaded media files, with GIFs limited to 2 MB and file uploads limited to 100 MB. If you need to increase the limit, you can [submit a ticket].

tip

• For how to personalize the remote push notification received by the recipient when offline, see Remote Push Notifications.
• Custom message types do not support the offline message to push mechanism by default. If support is needed, 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 of the media file (indicating its location) as a parameter when constructing the media message content. In this case, your file will not be hosted on RC's server. When you send a file message with a remote URL, there is no size limit for the file, 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] callback interface, and notify the SDK after the upload is successful, providing the remote address of the media file. The SDK will send the message after receiving the notification of successful upload.

String path = "file://image path";
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 the image to your own server*/
                    uploadImg(imgMsg.getPicFilePath(), new UploadListener() {
                        @Override
                        public void onSuccess(String url) {
                            // Upload successful, call the SDK's success method, passing back the remote address of the image
                            uploader.success(Uri.parse(url));
                        }


                        @Override
                        public void onProgress(float progress) {
                            //Refresh 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) {
                    //Send failed
                }

                @Override
                public void onProgress(Message message, int progress) {
                    //Send progress
                }

                @Override
                public void onSuccess(Message message) {
                    //Send successful
                }

                @Override
                public void onCanceled(Message message) {
                    //Send canceled
                }
            };

RongCoreClient.getInstance().sendMediaMessage(
        message, pushContent, pushData, sendMediaMessageCallbackWithUploader);

How to Send @ Messages

@ messages are not a predefined message type in RC's IM service (see the server-side documentation [Message Type Overview]). RC implements the mention others (@) feature by carrying mentionedInfo data in the message.

The [MentionedInfo] field in the MessageContent of the message stores the information of the mentioned (@) users. Both the built-in message types of the SDK and your custom message types directly or indirectly inherit from the [MessageContent] class.

RC supports adding mentionedInfo to the message content when sending messages to groups.