Sending Messages

IMKit's built-in chat UI already implements the functionality and interface for sending various message types (some message types require plugin support). When you need to send messages in a custom UI, you can use the message-sending methods provided by the IMKit core class RCIM. These methods not only enable message sending but also trigger updates in IMKit's built-in UIs.

IMKit supports sending both regular messages and media messages (refer to Message Introduction). The parent class for regular messages is RCMessageContent, while the parent class for media messages is RCMediaMessageContent. The key difference between sending media messages and regular messages lies in whether there's an upload process.

tip

• Always use the message-sending methods under IMKit's core class RCIM; otherwise, UI updates won't be triggered.
• Use the sendMessage method for regular messages and sendMediaMessage for media messages.
• IMKit SDK enforces a message rate limit of 5 messages per second.

Sending Regular Messages

Before sending a message, construct an RCMessage object. This object contains the regular message content to be sent, which is a subclass of RCMessageContent, such as text messages ([RCTextMessage]).

When you call RCIM's message-sending methods, the SDK triggers updates in the built-in conversation list and chat UIs.

Interface Specification

- (RCMessage *)sendMessage:(RCMessage *)message
               pushContent:(nullable NSString *)pushContent
                  pushData:(nullable NSString *)pushData
              successBlock:(nullable void (^)(RCMessage *successMessage))successBlock
                errorBlock:(nullable void (^)(RCErrorCode nErrorCode, RCMessage *errorMessage))errorBlock;

The sendMessage method directly provides parameters for controlling push notification content (pushContent) and additional push data (pushData). However, if you need finer control over offline push notifications—such as customizing titles, content, icons, or third-party vendor-specific configurations—use the message push attributes instead. See Customizing Message Push Notifications. Note that chatroom conversations don't support offline messaging mechanisms and thus don't support offline-to-push conversion.

• For SDK built-in message types like [RCTextMessage], these parameters can be set to nil. When such messages trigger offline push notifications, RC's server will use default pushContent values for each built-in message type. For default push content formats, see User Content Message Formats.
• For custom message types requiring offline push support, you must provide the pushContent field to RC; otherwise, users won't receive offline push notifications.
• For custom message types that don't need remote push support (e.g., app-level operational commands implemented via custom messages), leave pushContent empty.
• The MessagePushConfig settings in RCMessage's push attributes will override these parameters and offer additional configuration capabilities, such as custom push titles. See Customizing Message Push Notifications.

Parameter Description

Parameter	Type	Description
message	RCMessage	The message object to send. Required fields include conversation type (conversationType), target ID (targetId), and message content (content). See the RCMessage structure in Message Introduction.
pushContent	NSString	Modifies or specifies the push notification content displayed in the notification bar. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes. Set to nil to use RC's default push content. Note: Custom message types have no defaults. Provide pushContent here or in push attributes for personalized offline push notifications.
pushData	NSString	Additional push data. Can be nil. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes.
successBlock	Block	Callback for successful message sending.
errorBlock	Block	Callback for failed message sending.

Example Code

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

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


[[RCIM sharedRCIM]
  sendMessage:message
  pushContent:nil
  pushData:nil
  successBlock:^(RCMessage *successMessage) {
        //Success
    }
    errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
        //Failure
    }];

Sending Media Messages

For media messages, the content field of the RCMessage object must contain a subclass of RCMediaMessageContent, representing the media message content. Examples include image messages ([RCImageMessage]), GIF messages ([RCGIFMessage]), etc. Other built-in media message types include file messages ([RCFileMessage]), location messages ([RCLocationMessage]), HQ voice messages ([RCHQVoiceMessage]), and short video messages ([RCSightMessage]). It's recommended to integrate the corresponding IMKit plugins first.

Image message content ([RCImageMessage]) supports sending original-quality images.

Use the sendMediaMessage method for sending media messages. The SDK generates thumbnails for images, short videos, etc., compresses them according to default compression settings, uploads the media files to RC's default file server (file storage duration), and sends the message after updating the remote media URL. Original-quality images won't be compressed if configured as such.

Calling RCIM's message-sending methods triggers updates in the built-in conversation list and chat UIs.

Interface Prototype

- (RCMessage *)sendMediaMessage:(RCMessage *)message
                    pushContent:(nullable NSString *)pushContent
                       pushData:(nullable NSString *)pushData
                       progress:(nullable void (^)(int progress, RCMessage *progressMessage))progressBlock
                   successBlock:(nullable void (^)(RCMessage *successMessage))successBlock
                     errorBlock:(nullable void (^)(RCErrorCode nErrorCode, RCMessage *errorMessage))errorBlock
                         cancel:(nullable void (^)(RCMessage *cancelMessage))cancelBlock;

The sendMediaMessage method directly provides parameters for controlling push notification content (pushContent) and additional push data (pushData). However, if you need finer control over offline push notifications—such as customizing titles, content, icons, or third-party vendor-specific configurations—use the message push attributes instead. See Customizing Message Push Notifications. Note that chatroom conversations don't support offline messaging mechanisms and thus don't support offline-to-push conversion.

• For SDK built-in message types like [RCImageMessage], these parameters can be set to nil. When such messages trigger offline push notifications, RC's server will use default pushContent values for each built-in message type. For default push content formats, see User Content Message Formats.
• For custom message types requiring offline push support, you must provide the pushContent field to RC; otherwise, users won't receive offline push notifications.
• For custom message types that don't need remote push support (e.g., app-level operational commands implemented via custom messages), leave pushContent empty.
• The MessagePushConfig settings in RCMessage's push attributes will override these parameters and offer additional configuration capabilities, such as custom push titles. See Customizing Message Push Notifications.

Parameter Description

Parameter	Type	Description
message	RCMessage	The message object to send. Required fields include conversation type (conversationType), target ID (targetId), and message content (content). See the RCMessage structure in Message Introduction.
pushContent	NSString	Modifies or specifies the push notification content displayed in the notification bar. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes. Set to nil to use RC's default push content. Note: Custom message types have no defaults. Provide pushContent here or in push attributes for personalized offline push notifications.
pushData	NSString	Additional push data. Can be nil. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes.
progressBlock	Block	Callback for media upload progress.
successBlock	Block	Callback for successful message sending.
errorBlock	Block	Callback for failed message sending.
cancel	Block	Callback for canceled sending.

Example Code

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

RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                            targetId:@"targetId"
                                           direction:MessageDirection_SEND
                                             content:mediaMessageContent];
[[RCIM sharedRCIM] sendMediaMessage:message
                        pushContent:nil
                           pushData:nil
                           progress:^(int progress, RCMessage *progressMessage) {
                                //Media upload progress
                            }
                            successBlock:^(RCMessage *successMessage) {
                                //Success
                            }
                            errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
                                //Failure
                            }
                            cancel:^(RCMessage *cancelMessage) {
                                //Canceled
                            }];

tip

If media files have already been uploaded successfully (i.e., the media message already has a remote URL), you can send it directly as a regular message.

Sending Media Messages with Custom Server Upload

tip

Available since SDK v5.3.5.

Starting from v5.3.5, IMKit SDK supports letting apps handle media file uploads independently (e.g., to their own servers) before sending messages, while the SDK updates UI states. Implement media file upload in the uploadPrepareBlock of sendMediaMessage.

• During upload, call updateBlock and errorBlock of [RCUploadMediaStatusListener] to notify IMKit SDK of upload progress and status, which will update the UI.
• After upload completes, obtain the remote file URL. Get the current RCMessage object via the currentMessage property of [RCUploadMediaStatusListener], then set the corresponding URL field in the message's content.
• Call successBlock of [RCUploadMediaStatusListener] to notify the SDK that upload is complete.

Interface Prototype

- (RCMessage *)sendMediaMessage:(RCMessage *)message
                    pushContent:(nullable NSString *)pushContent
                       pushData:(nullable NSString *)pushData
                  uploadPrepare:(nullable void (^)(RCUploadMediaStatusListener *uploadListener))uploadPrepareBlock
                       progress:(nullable void (^)(int progress, long messageId))progressBlock
                   successBlock:(nullable void (^)(long messageId))successBlock
                     errorBlock:(nullable void (^)(RCErrorCode errorCode, long messageId))errorBlock
                         cancel:(nullable void (^)(long messageId))cancelBlock;

Parameter Description

Parameter	Type	Description
message	RCMessage	The message object to send. Required fields include conversation type (conversationType), target ID (targetId), and message content (content). See the RCMessage structure in Message Introduction.
pushContent	NSString	Modifies or specifies the push notification content displayed in the notification bar. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes. Set to nil to use RC's default push content. Note: Custom message types have no defaults. Provide pushContent here or in push attributes for personalized offline push notifications.
pushData	NSString	Additional push data. Can be nil. You can also configure this in RCMessage's push attributes (RCMessagePushConfig), which will override this setting. See Configuring Message Push Attributes.
uploadPrepareBlock	Block	Callback for sending media messages with custom server upload.
progressBlock	Block	Callback for media upload progress.
successBlock	Block	Callback for successful message sending.
errorBlock	Block	Callback for failed message sending.
cancel	Block	Callback for canceled sending.

Example Code

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

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

[[RCIM sharedRCIM] sendMediaMessage:message
                        pushContent:nil
                           pushData:nil
                      uploadPrepare:^(RCUploadMediaStatusListener *uploadListener) {
    RCMessage *currentMessage = uploadListener.currentMessage;
    // During media upload, call updateBlock, successBlock, and errorBlock in the listener to notify IMKit SDK of progress and status for UI updates.
    if ([currentMessage.content isKindOfClass:[RCImageMessage class]]) {
        RCImageMessage *content = (RCImageMessage *)currentMessage.content;
        content.remoteUrl = remoteUrl;
        uploadListener.successBlock(content)};
}
    progress:^(int progress, RCMessage *progressMessage) {
    //Media upload progress
}
    successBlock:^(RCMessage *successMessage) {
    //Success
}
    errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
    //Failure
}
    cancel:^(RCMessage *cancelMessage) {
    //Canceled
}];

Disabling Push Notifications for Messages

When recipients are offline, RC's server by default triggers push services to deliver messages via push channels (whether the server triggers pushes is also affected by app-level and user-level Do Not Disturb settings).

Sometimes app users may want to specify that certain messages shouldn't trigger pushes when sending. IMKit provides this capability but doesn't implement it in the UI. To achieve this:

1. Intercept messages via the willSendMessage callback in your app's RCConversationViewController subclass (inherited from the conversation UI). See UI Event Listeners in IMKit's conversation UI. Alternatively, implement message interception via a separate delegate. See Message Interception.

2. Obtain the RCMessage object.

   • For SDK versions < 5.3.5, assemble the RCMessage object using the RCMessageContent obtained from the callback.
   • For SDK versions ≥ 5.3.5, directly obtain the RCMessage object via message interception.

3. Set messageConfig's disableNotification to YES to disable push notifications for this message. When recipients come back online, they'll automatically receive the message via RC's server-side offline message cache (stored for up to 7 days) for one-to-one, group, and system conversations.

   RCMessage *message = [[RCMessage alloc]
     initWithType:ConversationType_PRIVATE
     targetId:@"targetId"
     direction:MessageDirection_SEND
     content:someMsg];
   
   message.messageConfig.disableNotification = YES;

4. Call the message-sending method again to resend the message.

Customizing Message Push Notifications

IMKit supports adding personalized configurations (RCMessagePushConfig) to individual messages' push behaviors but doesn't implement this in the UI. To use this, intercept messages during sending to add configurations, similar to Disabling Push Notifications for Messages.

RCMessagePushConfig provides the following capabilities. For details, see Configuring Message Push Attributes in the APNs Push Development Guide.

• Custom push titles and notification content
• Custom notification bar icons
• Add additional remote push data
• Bypass recipient client settings to force display of notification content
• Other APNs or Android push channel-specific configurations