Send Messages

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

Introduction to Message Content Types

The [RCMessage] object defined by the IMLib SDK contains two main types of message content in its content property: regular message content and media message content. The superclass for regular message content is [RCMessageContent], and the superclass for media message content is [RCMediaMessageContent]. The key difference between sending media messages and regular messages is whether there is an upload process for the data.

Feature	Message Content Type	Superclass	Description
Text Message	[RCTextMessage]	RCMessageContent	The content of a text message.
Quote Reply	[RCReferenceMessage]	RCMessageContent	The content of a quoted message, used to implement the quote reply feature.
Image Message	[RCImageMessage]	RCMediaMessageContent	The content of an image message, supporting sending the original image.
GIF Message	[RCGIFMessage]	RCMediaMessageContent	The content of a GIF message.
File Message	[RCFileMessage]	RCMediaMessageContent	The content of a file message.
Voice Message	[RCHQVoiceMessage]	RCMediaMessageContent	The content of a high-quality voice message.
Mention Others (@ Message)	Not Applicable	Not Applicable	@ messages are not a predefined message type. 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 rate limit for sending messages, with a maximum of 5 messages per second.

This document uses the RCIMClient core class of the IMLib SDK (or RCCoreClient) to send messages.

Regular Messages

Regular messages refer to text messages, quoted messages, etc., that do not involve media file uploads. The message content of regular messages is a subclass of RCMessageContent, such as text message content ([RCTextMessage]), or custom regular message content.

Constructing Regular Messages

Before sending, you need to construct an [RCMessage] object, specifying the conversation type (one-to-one chat, group chat, chatroom), the Target ID of the conversation, the message direction (send or receive), and the message content. The following example constructs a message object containing text message content ([RCTextMessage]).

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"Test text message"];
RCConversationType conversationType = ConversationType_PRIVATE

RCMessage *message = [[RCMessage alloc]
  initWithType:conversationType
  targetId:@"targetId"
  direction:MessageDirection_SEND
  content:messageContent];

Sending Regular Messages

If the [RCMessage] object contains regular message content, use the sendMessage method of the IMLib SDK core class RCCoreClient (or RCIMClient) to send the message.

The disableUpdateLastMessage property of RCMessaage controls whether to update to the latest message in the conversation, default is NO: update, YES: do not update

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"Test text message"];

RCMessage *message = [[RCMessage alloc]
  initWithType:ConversationType_PRIVATE
  targetId:@"targetId"
  direction:MessageDirection_SEND
  content:messageContent];


[[RCCoreClient sharedRCCoreClient]
  sendMessage:message
  pushContent:nil
  pushData:nil
  attached:^(RCMessage *successMessage) {
        // Successfully stored in the database
    }
  successBlock:^(RCMessage *successMessage) {
        // Success
    }
    errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
        // Failure
    }];

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 [RCMessagePushConfig], which includes pushContent and pushData, and provides more push notification configuration capabilities, such as title, content, icon, or other third-party vendor-specific configurations. For details, see Remote Push Notifications.

Regarding whether to configure the input parameters or the pushContent in the RCMessage's messagePushConfig property, refer to the following:

• If the message type is a [predefined message type of the IM service] in the [user content 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 message type, see [User Content Message Format].
• If the message type is a notification or signaling type in the [predefined message type of the IM service] (except for "recall command messages") and needs to support remote push notifications, pushContent must be filled in; otherwise, the recipient will not receive a remote push notification when offline. If no remote push is required, 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 sessions do not support the offline message mechanism, so they also do not support offline message to push conversion.

Parameter	Type	Description
message	[RCMessage]	The message body to be sent. Required properties include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the structure of RCMessage, see [Message Introduction].
pushContent	NSString	Modify or specify the content displayed in the remote message push notification bar. You can also configure this in the push properties of RCMessage (RCMessagePushConfig), which will override this configuration. For details, see [Configure Message Push Properties].
pushData	NSString	Push additional information. Can be set to nil. You can also configure this in the push properties of RCMessage (RCMessagePushConfig), which will override this configuration. For details, see [Configure Message Push Properties].
attachedBlock	Block	Callback when the message is successfully stored in the message database.
successBlock	Block	Callback when the message is successfully sent.
errorBlock	Block	Callback when the message fails to send.

Through the callback of the RCMessage's sendMessage method, the RC server will always notify you whether your message has been successfully sent. If the sending fails due to any issue, the exception will be returned via the callback method.

tip

• For how to customize 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. For 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 of media messages is a subclass of RCMeidaMessageContent, such as high-quality voice message content ([RCHQVoiceMessage]), or your custom media message content.

Constructing Media Messages

Before sending, you need to construct an [RCMessage] object. The content field of the media message RCMessage object must be passed a subclass instance of [RCMediaMessageContent], representing the media message content. For example, image message content ([RCImageMessage]), GIF message content ([RCGIFMessage]), or custom media message content inherited from [RCMediaMessageContent].

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

RCImageMessage *mediaMessageContent = [RCImageMessage messageWithImageURI:@"path/to/image"];
mediaMessageContent.full YES; // Image messages support sending the original image

RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                            targetId:@"targetId"
                                           direction:MessageDirection_SEND
                                             content: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.

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

It is generally not recommended to modify the SDK's default compression configuration. If you need to adjust the SDK's compression quality, see 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 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.

The disableUpdateLastMessage property of RCMessaage controls whether to update to the latest message in the conversation, default is NO: update, YES: do not update

[[RCCoreClient sharedCoreClient] sendMediaMessage:message
                                    pushContent:nil
                                       pushData:nil
                                       attached:^(RCMessage *successMessage) {
                                        // Successfully stored in the database
                                        }
                                       progress:^(int progress, RCMessage *progressMessage) {
                                        // Media upload progress
                                        }
                                        successBlock:^(RCMessage *successMessage) {
                                            // Success
                                        }
                                        errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
                                            // Failure
                                        }
                                        cancel:^(RCMessage *cancelMessage) {
                                            // Cancel
                                        }];

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 [RCMessagePushConfig], which includes pushContent and pushData, and provides more push notification configuration capabilities, such as title, content, icon, or other third-party vendor-specific configurations. For details, see Remote Push Notifications.

Regarding whether to configure the input parameters or the pushContent in the RCMessage's messagePushConfig property, refer to the following:

• If the message type is a [predefined message type of the IM service] in the [user content message format], such as [RCTextMessage], 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 message type, see [User Content Message Format].
• If the message type is a notification or signaling type in the [predefined message type of the IM service] (except for "recall command messages") and needs to support remote push notifications, pushContent must be filled in; otherwise, the recipient will not receive a remote push notification when offline. If no remote push is required, 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 sessions do not support the offline message mechanism, so they also do not support offline message to push conversion.

Parameter	Type	Description
message	[RCMessage]	The message body to be sent. Required properties include conversation type (conversationType), conversation ID (targetId), and message content (content). For details on the structure of RCMessage, see [Message Introduction].
pushContent	NSString	Modify or specify the content displayed in the remote message push notification bar. You can also configure this in the push properties of RCMessage (RCMessagePushConfig), which will override this configuration. For details, see [Configure Message Push Properties].
pushData	NSString	Push additional information. Can be set to nil. You can also configure this in the push properties of RCMessage (RCMessagePushConfig), which will override this configuration. For details, see [Configure Message Push Properties].
attachedBlock	Block	Callback when the message is successfully stored in the message database.
progressBlock	Block	Callback for media upload progress.
successBlock	Block	Callback when the message is successfully sent.
errorBlock	Block	Callback when the message fails to send.
cancel	Block	Callback when the sending is canceled.

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

The method for sending media messages defaults to uploading the media file to RC's file server. You can download media message files in the client application. RC has set 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 customize 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. For 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 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 limit on the file size, 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 of RCCoreClient, as follows:

• During the media file upload process, you can call the updateBlock and errorBlock of [RCUploadMediaStatusListener] to notify the SDK of the current upload progress and status of the media file.
• After the upload is complete, obtain the network file URL. Get the current RCMessage object through the currentMessage property of [RCUploadMediaStatusListener], and set the corresponding URL field in the content of the RCMessage object to the successfully uploaded network file URL.
• Call the successBlock of [RCUploadMediaStatusListener] to notify the SDK that the file upload is complete.

RCImageMessage *mediaMessageContent = [RCImageMessage messageWithImageURI:@"path/to/image"];
mediaMessageContent.full = YES; // Image messages support sending the original image

RCMessage *message = [[RCMessage alloc]
                        initWithType:ConversationType_PRIVATE
                            targetId:@"targetId"
                           direction:MessageDirection_SEND
                             content:mediaMessageContent];

[[RCCoreClient sharedCoreClient] sendMediaMessage:message
                                      pushContent:nil
                                         pushData:nil
                                         attached:^(RCMessage * _Nullable msg) {
} uploadPrepare:^(RCUploadMediaStatusListener * _Nonnull uploadListener) {
    RCMessage *currentMessage = uploadListener.currentMessage;
    //  App needs to call updateBlock, successBlock, and errorBlock in the listener when uploading media files
    if ([currentMessage.content isKindOfClass:[RCImageMessage class]]) {
        RCImageMessage *content = (RCImageMessage *)currentMessage.content;
        // After uploading to your server, get the image URL
        content.remoteUrl = @"https://www.test.com/img/test.jpg";
        uploadListener.successBlock(content);
    }
} progress:^(int progress, long messageId) {
    // Media upload progress, need to refresh the UI
}  success:^(long messageId) {
}    error:^(RCErrorCode errorCode, long messageId) {
}   cancel:^(long messageId) {
}];

How to Send @ Messages

@