Skip to main content

Sending and Receiving Messages

This document explains how to use the IMLib SDK to send and receive ultra group messages. Ultra group messaging requires methods from the RCCoreClient class.

Prerequisites​

We recommend reading Ultra Group Overview and Ultra Group Private Channel Overview first to understand how to use channels and ultra group channel features in your app.

tip

When users send/receive messages in the current channel chat UI, both the ultra group targetId and channelId must be verified. Messages will only display in the current channel UI if both IDs match. If messages appear in other chat UIs, this typically indicates an incorrect ultra group ID or channel ID.

Receiving Messages​

The message receiving methods for ultra group conversations are identical to those for one-to-one and group chats. Refer to Receiving Messages for implementation details.

tip

Ultra group conversations don't support offline messages. To retrieve messages received while offline, you'll need to fetch historical messages based on the last message in the ultra group conversation.

Constructing Message Objects​

Before sending messages, construct an RCMessage object. The message's conversationType field must specify the ultra group conversation type ConversationType_ULTRAGROUP. The targetId field represents the ultra group ID, while channelId represents the channel ID.

The IMLib SDK's RCMessage object can contain two main types of message content in its content property: regular message content and media message content. The parent class for regular messages is RCMessageContent, while media messages inherit from RCMediaMessageContent. The interfaces for sending media messages differ from regular messages, primarily due to the media upload process.

FeatureMessage Content TypeParent ClassDescription
Text MessageRCTextMessageRCMessageContentText message content
Quote ReplyRCReferenceMessageRCMessageContentQuote message content for implementing reply functionality
Image MessageRCImageMessageRCMediaMessageContentImage message content supporting original quality transmission
GIF MessageRCGIFMessageRCMediaMessageContentGIF message content
File MessageRCFileMessageRCMediaMessageContentFile message content
HQ Voice MessageRCHQVoiceMessageRCMediaMessageContentHigh-quality voice message content
Mentions (@)N/AN/AMentions aren't predefined message types. See Sending @ Messages.

These represent some of the built-in message content types in IMLib SDK. You can also create custom message types - use the sendMessage method for custom regular messages and sendMediaMessage for custom media messages. See Custom Message Types.

tip
  • Use sendMessage for regular messages and sendMediaMessage for media messages.
  • The client SDK enforces a rate limit of 5 messages per second.
  • For apps/environments activated after October 13, 2022, ultra groups include a default channel with ID RCDefault. Messages without specified channel IDs will be sent to this default channel.
  • For pre-October 13, 2022 ultra groups, messages without channel IDs won't belong to any channel. RC supports upgrading services to the new behavior, which affects multiple features including message sending/receiving, conversation retrieval, history clearing, and muting. Submit a ticket for migration details.

Regular Messages​

Regular messages include text messages, quote messages, and other types that don't involve media file uploads. These use subclasses of RCMessageContent, such as RCTextMessage for text content or custom regular message types.

Constructing Regular Messages​

Before sending ultra group regular messages, construct an RCMessage object by setting the conversation type to ultra group, specifying targetId (ultra group ID), channelId, message direction (send/receive), and message content. The example below constructs a message object containing text message content (RCTextMessage).

The disableUpdateLastMessage property of RCMessaage controls whether the message updates as the conversation's last message (default NO: updates; YES: doesn't update).

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

RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_ULTRAGROUP targetId:@"ultra group id" channelId:@"channel id" direction:MessageDirection_SEND content:messageContent];

Sending Regular Messages​

For RCMessage objects containing regular message content, use the sendMessage method from IMLib SDK's core class RCCoreClient.

Method Prototype​

- (void)sendMessage:(RCMessage *)message
        pushContent:(nullable NSString *)pushContent
           pushData:(nullable NSString *)pushData
           attached:(nullable void(^)(RCMessage *_Nullable message))attachedBlock
       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). Alternatively, you can use RCMessagePushConfig for more comprehensive push notification configuration including titles, content, icons, and vendor-specific settings. See Remote Notifications.

Guidelines for configuring pushContent:

  • For predefined [user content message types] like RCTextMessage, pushContent can be null. Offline notifications will use server-preset content. See User Content Message Formats for defaults.
  • For predefined notification/command message types (except "recall command messages") requiring remote notifications, pushContent is mandatory when recipients are offline. Omit if remote push isn't needed.
  • For custom message types, see Supporting Remote Push for Custom Messages.
  • Note: Chatroom conversations don't support offline messages or offline-to-push conversion.

Parameter Description​

ParameterTypeDescription
messageRCMessageMessage object to send. Required fields: conversationType, targetId, content. See RCMessage structure in Message Introduction.
pushContentNSStringCustomizes push notification content. Can also be configured in RCMessagePushConfig, which overrides this setting. See Configuring Push Properties.
pushDataNSStringAdditional push data. Can be nil. Configurable in RCMessagePushConfig, which overrides this setting. See Configuring Push Properties.
attachedBlockBlockCallback when message is successfully stored in local database.
successBlockBlockSuccess callback for message sending.
errorBlockBlockFailure callback for message sending.

Use RCCoreClient's sendMessage callbacks to confirm successful delivery to RC servers. Error callbacks provide failure details.

Example Code​

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

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


[[RCCoreClient sharedRCCoreClient]
  sendMessage:message
  pushContent:nil
  pushData:nil
  attached:^(RCMessage *successMessage) {
        //Database storage success
    }
  successBlock:^(RCMessage *successMessage) {
        //Success
    }
    errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
        //Failure
    }];
tip

Media Messages​

Media messages include images, GIFs, files, and other types requiring media file uploads. These use subclasses of RCMeidaMessageContent, such as RCHQVoiceMessage for HQ voice messages or custom media message types.

Constructing Media Messages​

Before sending, construct an RCMessage object. The content field must contain a subclass of RCMediaMessageContent, such as RCImageMessage for images, RCGIFMessage for GIFs, or custom media message types inheriting from RCMediaMessageContent.

For image messages, use messageWithImageURI: with a valid local image path to construct RCImageMessage content, which supports original quality transmission.

The disableUpdateLastMessage property of RCMessaage controls whether the message updates as the conversation's last message (default NO: updates; YES: doesn't update).

RCImageMessage *mediaMessageContent = [RCImageMessage messageWithImageURI:@"path/to/image"];
mediaMessageContent.full = YES; // Enable original quality transmission
RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_ULTRAGROUP
                                            targetId:@"targetId"
                                            channelId:@"channelId" 
                                           direction:MessageDirection_SEND
                                             content:mediaMessageContent];
tip

Before sending, images are compressed and thumbnails are generated for chat UI display. GIFs aren't thumbnailed or compressed.

  • Image thumbnails: IMLib SDK generates a large image at 30% quality (max 240px longest side) for upload and display in chat UIs.
  • Images: Unless sending originals, SDK compresses images to 85% quality (max 1080px longest side) for upload.
  • Generally avoid modifying default compression settings. For IMLib SDK 5.16.1+, use [RCLocalConfiguration sharedInstance] properties to configure compression. For earlier versions, see Modifying Default Image/Video Compression Settings.

Sending Media Messages​

Use sendMediaMessage for media messages. IMLib SDK generates thumbnails for images/short videos, compresses them per default settings, uploads to RC's file server (storage duration), then sends the message. Original quality images bypass compression.

Method Prototype​

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

The sendMediaMessage method provides direct parameters for push notification content (pushContent) and additional data (pushData). Alternatively, use RCMessagePushConfig for comprehensive push configuration including titles, content, icons, and vendor-specific settings. See Remote Notifications.

Guidelines for configuring pushContent:

Parameter Description​

ParameterTypeDescription
messageRCMessageMessage object to send. Required fields: conversationType, targetId, content. See RCMessage structure in Message Introduction.
pushContentNSStringCustomizes push notification content. Can also be configured in RCMessagePushConfig, which overrides this setting. See Configuring Push Properties.
pushDataNSStringAdditional push data. Can be nil. Configurable in RCMessagePushConfig, which overrides this setting. See Configuring Push Properties.
attachedBlockBlockCallback when message is successfully stored in local database.
progressBlockBlockCallback for media upload progress.
successBlockBlockSuccess callback for message sending.
errorBlockBlockFailure callback for message sending.
cancelBlockCallback for cancellation.

Sample Code​

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

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

The media message sending method automatically uploads media files to RC's file server by default. You can download media message files in your client application. RC imposes size limits on uploaded media files: 2 MB for GIFs and 100 MB for files. If you need to increase these limits, you can submit a ticket.

tip

Sending Media Messages Uploaded to Your Own Server​

You can directly send files already hosted on your server. Pass the media file's URL (indicating its location) as a parameter when constructing the media message content. In this case, your files won't be hosted on RC servers. When sending file messages with remote URLs, there are no size restrictions, and you can directly use the sendMessage method to send the message.

If you want the SDK to send the message after your upload succeeds, you can use the sendMediaMessage method of RCCoreClient as follows:

  1. Call the sendMediaMessage: interface to send media messages. During media file upload, you can invoke updateBlock and errorBlock of RCUploadMediaStatusListener to notify the IMLib SDK about the current upload progress and status.
  2. After upload completes, 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.
  3. Call the successBlock of RCUploadMediaStatusListener to notify the IMLib SDK that file upload is complete.
RCImageMessage *mediaMessageContent = [RCImageMessage messageWithImageURI:@"path/to/image"];
mediaMessageContent.full = YES; // Image messages support sending as original image

RCMessage *message = [[RCMessage alloc]
                        initWithType:ConversationType_ULTRAGROUP
                            targetId:@"targetId"
                            channelId:@"channelId"
                           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;
    //  When uploading media files, the app needs to call updateBlock, successBlock, and errorBlock in the listener
    if ([currentMessage.content isKindOfClass:[RCImageMessage class]]) {
        RCImageMessage *content = (RCImageMessage *)currentMessage.content;
        // Image URL obtained after uploading to your server
        content.remoteUrl = @"https://www.test.com/img/test.jpg";
        uploadListener.successBlock(content);
    }
} progress:^(int progress, long messageId) {
    //Media upload progress, requires manual UI refresh
}  success:^(long messageId) {
}    error:^(RCErrorCode errorCode, long messageId) {
}   cancel:^(long messageId) {
}];

How to Send @ Messages​

@ messages are not a predefined message type in RC's IM service (see server documentation Message Type Overview). You can implement the function of @ others by setting mentionedInfo data in messages.

You can set information about @ed people in the RCMentionedInfo field of the message's RCMessageContent. Both SDK built-in message types and your custom message types directly or indirectly inherit from the RCMessageContent class, so they all support setting @ information.

MentionedInfo parameters:

ParameterTypeDescription
typeRCMentionedType(Required) Specifies the type of MentionedInfo. RC_Mentioned_All means everyone needs to be mentioned (@). RC_Mentioned_Users means only some people need to be @ed, and the mentioned people must be specified in userIdList.
userIdListNSArrayCollection of user IDs to be mentioned (@). Required when type is RC_Mentioned_Users. Starting from version 5.3.1, it supports mentioning some people in userIdList when type is RC_Mentioned_All. The receiving end can obtain userIdList data through RCMentionedInfo.
mentionedContentNSStringContent displayed in the notification bar when offline push is triggered. If nil, the default prompt ("Someone @ed you") is displayed. The mentionedContent carried by @ messages has the highest priority and will override all default or custom pushContent data.

The following example shows sending a text message mentioning some users to a group chat session.

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"Test text message"];
// Set information about @ed people
messageContent.mentionedInfo = [[RCMentionedInfo alloc]
                        initWithMentionedType:RC_Mentioned_Users
                                   userIdList:@[@"userId1", @"userId2"]
                             mentionedContent:nil];

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

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

After the IMLib SDK receives the message, you need to process the @ message data. You can obtain the RCMentionedInfo object carried by the message object after getting the RCMessage (message object).

Remote Notifications​

tip

Chatroom sessions do not support offline message mechanisms, and therefore do not support offline message-to-push conversion.

If your application has configured third-party push notifications with RC, when the message recipient is offline, the RC server will decide whether to trigger remote push based on message type, recipient's supported push channels, recipient's Do Not Disturb settings, etc.

Remote push notifications are generally displayed in the system's notification bar. RC's built-in message types will display notification titles and content in the notification bar by default. For default push notification content of various message types, see User Content Message Formats.

Configuring Message Push Attributes​

If you need personalized offline push notifications, you can modify or specify the notification title, content, and other attributes of remote push notifications in the following ways:

  • Control push notification content by setting the pushContent parameter in the input parameters of the sendMessage and sendMediaMessage methods.
  • If you need to control more attributes of offline push notifications, such as title, content, icon, or personalized configurations based on third-party vendor channels, use the push attributes (RCMessagePushConfig) of RCMessage for configuration.
tip

Compared to the pushContent and pushData input parameters when sending messages, the configurations in MessagePushConfig have higher priority. When sending messages, if you have configured the messagePushConfig property of RCMessage, the configurations in messagePushConfig will be used first.

You can personalize the push behavior of individual messages by setting the messagePushConfig property of RCMessage. For example:

  • Customize push title and notification content
  • Customize notification bar icons
  • Add remote push additional information
  • Bypass recipient client configurations and force display of notification content in push notifications
  • Other personalized configurations supported by APNs, HarmonyOS, or Android push channels
RCTextMessage *txtMsg = [RCTextMessage messageWithContent:@"Test text message"];


RCMessage *message = [[RCMessage alloc]
  initWithType:ConversationType_ULTRAGROUP
  targetId:@"targetId"
  channelId:@"channelId"
  direction:MessageDirection_SEND
  content:txtMsg];

RCMessagePushConfig *pushConfig = [[RCMessagePushConfig alloc] init];
pushConfig.disablePushTitle = NO;
pushConfig.pushTitle = @"Notification Title";
pushConfig.pushContent = @"Notification Content";
pushConfig.pushData = @"Notification's pushData";
pushConfig.templateId = @"templateId";
pushConfig.iosConfig.threadId = @"iOS ID for notification grouping";
pushConfig.iosConfig.apnsCollapseId = @"iOS ID for notification replacement";
pushConfig.iosConfig.richMediaUri = @"iOS custom notification bar message right icon URL";
pushConfig.androidConfig.notificationId = @"Android notification ID";
pushConfig.androidConfig.channelIdMi = @"Xiaomi's channelId";
pushConfig.androidConfig.channelIdHW = @"Huawei's channelId";
pushConfig.androidConfig.categoryHW = @"Huawei's Category";
pushConfig.androidConfig.channelIdOPPO = @"OPPO's channelId";
pushConfig.androidConfig.typeVivo = @"vivo's classification";
pushConfig.androidConfig.categoryVivo = @"vivo's Category";
pushConfig.hmosConfig.imageUrl = "HarmonyOS notification bar message right large icon URL";
pushConfig.hmosConfig.category = "HarmonyOS push message classification";
pushConfig.forceShowDetailContent = YES;
message.messagePushConfig = pushConfig;

Message push attribute descriptions (RCMessagePushConfig) provide the following parameters:

ParameterTypeDescription
disablePushTitleBOOLWhether to block notification titles. This property only applies when the target user is on an iOS platform. Android third-party push platforms require notification titles as mandatory, so this is not currently supported.
pushTitleNSStringPush title. The push title specified here has the highest priority. If not set, refer to User Content Message Formats for default push notification titles and push notification content descriptions of built-in message types.
pushContentNSStringPush content. The push content specified here has the highest priority. If not set, refer to User Content Message Formats for default push notification titles and push notification content descriptions of built-in message types.
pushDataNSStringRemote push additional information. If not provided, the pushData of the sent message is used.
forceShowDetailContentBOOLWhether to force display of notification details. When the target user has set push notifications to not display message details via RCPushProfile's - (void)updateShowPushContentStatus:(BOOL)isShowPushContent success:(void (^)(void))successBlock error:(void (^)(RCErrorCode status))errorBlock;, you can use this parameter to force display of push details for this message.
templateIdNSStringPush template ID. After setting, the language content set in the template will be matched based on the language environment set by the target user via the SDK RCPushProfile's setPushLauguageCode for push. If no match is successful, the default content will be used for push. Template content is set in "Console - Custom Push Copy". For specific operations, see Configure and Use Custom Multi-Language Push Templates.
iOSConfigRCiOSConfigiOS platform-related configurations. See RCiOSConfig Attribute Descriptions.
androidConfigRCAndroidConfigAndroid platform-related configurations. RCiOSConfig Attribute Descriptions.
hmosConfigRCHarmonyOSConfigHarmonyOS platform-related configurations. RCHarmonyOSConfig Attribute Descriptions.

  • RCiOSConfig Attribute Descriptions

    ParameterTypeDescription
    threadIdNSStringiOS notification grouping ID. Notifications with the same threadId will be grouped together (supported since iOS 10)
    apnsCollapseIdNSStringiOS notification replacement ID. When apnsCollapseId is identical, new notifications will replace old ones (max 64 bytes, supported since iOS 10)
    richMediaUriNSStringCustom 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.
    interruptionLevelNSStringApplies to iOS 15 and later systems. Values: passive, active (default), time-sensitive, or critical. For details, refer to APNs interruption-level. In iOS 15+, system features like "Scheduled Summary" and "Focus Mode" may prevent important notifications (e.g., balance changes) from being noticed promptly. Consider setting this field. Supported since SDK version 5.6.7.

  • RCAndroidConfig Attribute Descriptions

    ParameterTypeDescription
    notificationIdNSStringAndroid push notification unique identifier. Currently supports Xiaomi and Huawei push platforms. By default, developers don't need to set this - when a message generates a push notification, the message's messageUId is used as the notificationId.
    channelIdMiNSStringXiaomi channel ID. For messages targeting Xiaomi push channels. If developers have integrated Xiaomi Push and need to specify channelId, they can obtain it from Android developers. The channelId is created by developers themselves.
    miLargeIconUrlNSString(This field is no longer valid as Xiaomi has officially discontinued support for this capability) URL for the notification image used in Xiaomi notification-type pushes. Image requirements: 120 * 120px, PNG or JPG format.
    Supported since version 5.1.7. Works with both MIUI China edition (requires MIUI 12+) and international edition.
    channelIdHWNSStringHuawei channel ID. For messages targeting Huawei push channels. If developers have integrated Huawei Push and need to specify channelId, they can obtain it from Android developers. The channelId is created by developers themselves.
    hwImageUrlNSStringURL for a custom small notification icon (displayed on the right side) in Huawei push notifications. If not set, no icon will be displayed. 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 version 5.1.7.
    categoryHWNSStringHuawei push channel message self-classification identifier. Default is empty. Value must be uppercase letters, e.g., IM. This field becomes valid after the app completes [Huawei Self-Classification Rights Application] or Special Permission Application as required by Huawei. See Huawei's official documentation Huawei Message Classification Standards. This field takes precedence over the Huawei Push Category configured for the App Key in the Console. Supported since SDK version 5.4.0.
    importanceHWRCImportanceHwHuawei push notification priority level. RCImportanceHwLow indicates silent notification (no sound/vibration when message arrives). RCImportanceHwNormal indicates strong notification (sound/vibration when message arrives). Actual notification behavior depends on categoryHW value, Console-configured category, or Huawei Smart Classification results. Supported since SDK version 5.1.3.
    imageUrlHonorNSStringURL for a custom large notification icon (displayed on the right side) in Honor push notifications. If not set, no icon will be displayed. 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.
    importanceHonorRCimportanceHonorHonor push notification classification for Android, determining user device notification behavior. RCImportanceHonorLow indicates marketing/informational messages. RCImportanceHonorNormal (default) indicates service/communication messages. Supported since SDK version 5.6.7.
    typeVivoNSStringVIVO push service message type. Options: 0 (marketing messages) and 1 (system messages). Corresponds to VIVO push service's classification field. See [VIVO Push Message Classification].
    categoryVivoNSStringVIVO push service message subcategory. Example: IM (instant message). Corresponds to VIVO push service's category field. For detailed category values, see [VIVO Push Message Classification]. If specifying subcategory categoryVivo, you must also specify typeVivo (system or marketing message). Ensure the subcategory complies with VIVO's official requirements for allowed content. categoryVivo takes precedence over the VIVO Push Category configured for the App Key in the Console. Supported since SDK version 5.4.2.
    channelIdOPPONSStringOPPO channel ID. For messages targeting OPPO push channels. If developers have integrated OPPO Push and need to specify channelId, they can obtain it from Android developers. The channelId is created by developers themselves.
    fcmCollapseKeyNSStringFCM push notification group ID. Supported since SDK version 5.1.3. Note: When using this field, ensure the FCM push configuration in the Console uses Notification Message as the push method.
    fcmImageUrlNSStringURL for FCM push notification icon (displayed on the right side). If not set, no icon will be displayed. Supported since SDK version 5.1.3. Note: When using this field, ensure the FCM push configuration in the Console uses Certificate as the authentication method and Notification Message as the push method.
    fcmChannelIdNSStringFCM channel ID. For messages targeting FCM push channels. If developers have integrated FCM push and need to specify channelId, they can obtain it from Android developers. The channelId is created by developers themselves.

    Channel IDs need to be created by Android developers as follows:

    Push ChannelConfiguration Instructions
    HuaweiOn the app side, call the Android SDK's Channel ID creation interface to create Channel IDs
    XiaomiCreate Channel IDs on Xiaomi's open platform management console or through Xiaomi's server API
    OPPOOn the app side, call the Android SDK to create Channel IDs; register these Channel IDs on OPPO's management console to maintain consistency
    vivoCall the server API to create Channel IDs
    • RCHarmonyOSConfig Attribute Descriptions
ParameterTypeDescription
imageUrlNSStringHarmonyOS notification bar message large icon URL (right side). Supported formats: png, jpg, jpeg, heif, gif, bmp. Image dimensions (length*width) must be < 25,000 pixels. If the image doesn't meet requirements, the notification message won't display on the device.
categoryNSStringHarmonyOS push message category (default: empty). Category values must be uppercase letters. For details, see HarmonyOS Category Documentation.

Supporting Remote Push Notifications for Custom Messages​

The IMLib SDK implements remote notification titles and content for built-in message types (see User Content Message Formats). If you're sending custom message types, you must provide the pushContent field yourself; otherwise, recipient users won't receive offline push notifications. Details:

  • For custom message types requiring offline push support, you must provide the pushContent field either through message parameters or push attributes in IMLib SDK. 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.

Disabling Push Notifications for Messages​

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

Sometimes app users may want to specify that a particular message shouldn't trigger a push notification when sent. This requirement can be achieved through the MessageConfig configuration of the RCMessage object.

In the following example, we set disableNotification in messageConfig to YES to disable push notifications for this message. When the recipient comes back online, they'll automatically receive one-to-one, group, and system conversation messages through RC's offline message cache (retained for up to 7 days). Ultra group messages don't support offline messaging and must be actively pulled.

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

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

message.messageConfig.disableNotification = YES;

Passing Custom Data​

If you need to pass custom data to the receiving end, you can do so through:

  • The extra field in the message content RCMessageContent, which is sent along with the instant message to the receiving end. The recipient can retrieve this field from the message content when receiving it online. Note this differs from the extra field in RCMessage, which is a local operation field and isn't sent to the server.

  • Remote push additional information pushData. You can set pushData directly in the input parameters of sendMessage and sendMediaMessage, or use the field with the same name in message push attributes (the latter will override the former).

tip

pushData is only delivered to the receiving device when the message triggers an offline remote push. When the recipient receives a remote push notification, they can retrieve the passed data through the appData field in the push data. See Get Push Data in Integrating APNs Remote Push.

Handling Failed Message Sending​

  1. For message types that are stored locally on the client (see Message Type Overview), if the errorBlock callback is triggered, the app can temporarily display the failed message in the UI and cache the RCMessage instance thrown by errorBlock, then retry sending by calling sendMessage or sendMediaMessage at an appropriate time.
  2. For messages that are not stored locally on the client, if sending fails (errorBlock), the app can cache the message instance and retry sending, or create a new message instance to send.
tip

Note that for message types that are stored locally, if you resend after a failed send without reusing the RCMessage instance thrown by errorBlock, but instead resend a new message with the same content, the local message list will contain two duplicate messages.

Last updated on