Skip to main content

Sending Messages

IMKit's built-in chat UI already supports sending various message types (some require plugin integration). When customizing your chat interface, you can use the core IMCenter class methods to send messages. These methods not only handle message delivery but also trigger updates in IMKit's built-in interfaces.

IMKit supports sending both standard messages and media messages (see [Message Introduction]). The parent class for standard messages is [MessageContent], while media messages inherit from [MediaMessageContent]. The key difference lies in whether data upload is required for media messages.

Important

  • Always use IMCenter methods for sending messages to ensure UI updates. Use sendMessage for standard messages and sendMediaMessage for media messages.
  • The client SDK enforces a rate limit of 5 messages per second.

Sending Standard Messages​

Construct a Message object before sending. The content field must contain a standard message (subclass of [MessageContent]), such as [TextMessage].

Interface​

IMCenter.getInstance().sendMessage(message, pushContent, pushData, callback);

Parameters​

ParameterTypeDescription
message[Message]The message object. See [Message Introduction] for structure details.
pushContentStringCustomizes push notification content. Can also be configured via MessagePushConfig in the message (overrides this parameter). See Custom Push Notifications.
  • Set to null to use RC's default push content (note: custom message types have no default).
  • Required for offline push notifications on custom message types.
pushDataStringAdditional push payload accessible via io.rong.push.notification.PushNotificationMessage#getPushData(). Can also be configured via MessagePushConfig.
callback[ISendMessageCallback]Message delivery callback

Example​

String targetId = "conversation ID";
ConversationType conversationType = ConversationType.PRIVATE;
TextMessage messageContent = TextMessage.obtain("Message content");

Message message = Message.obtain(targetId, conversationType, messageContent);

IMCenter.getInstance().sendMessage(message, null, null, new IRongCallback.ISendMessageCallback() {
        @Override
        public void onAttached(Message message) {}
        
        @Override
        public void onSuccess(Message message) {}
        
        @Override
        public void onError(Message message, RongIMClient.ErrorCode errorCode) {}
    });

The sendMessage method provides direct parameters for push content (pushContent) and push payload (pushData). For advanced push notification customization (e.g., title, icon, or platform-specific configurations), use MessagePushConfig instead (see Custom Push Notifications). Note: Chatrooms don't support offline messages or push notifications.

  • For SDK built-in message types like [TextMessage], these parameters can be null. RC server will use default push content when needed (see [User Content Message Formats]).
  • Custom message types requiring offline push must provide pushContent either here or via MessagePushConfig.
  • Business logic messages (e.g., commands) that don't need push can leave pushContent empty.
  • MessagePushConfig configurations override these parameters and offer more options (e.g., custom titles). See [Custom Push Notifications].

Sending Media Messages​

For media messages, the content field must contain a [MediaMessageContent] subclass like [ImageMessage] or [GIFMessage]. Other built-in media types include [FileMessage], LocationMessage, [HQVoiceMessage], and [SightMessage] (require respective plugins).

[ImageMessage] supports sending original/uncompressed images:

String targetId = "Target ID";
ConversationType conversationType = ConversationType.PRIVATE;
Uri localUri = Uri.parse("file://image_path"); // Local image path
boolean mIsFull = true; // Send original image
ImageMessage mediaMessageContent = ImageMessage.obtain(localUri, mIsFull);

Message message = Message.obtain(targetId, conversationType, mediaMessageContent);

Use sendMediaMessage for media messages. The SDK generates thumbnails, compresses media (per default compression settings), uploads to RC's file server (storage duration), then sends the message. Original images (when enabled) bypass compression.

IMCenter.getInstance().sendMediaMessage(message, null, null, new IRongCallback.ISendMediaMessageCallback() {
    @Override
    public void onProgress(Message message, int progress) {}
    
    @Override
    public void onCanceled(Message message) {}
    
    @Override
    public void onAttached(Message message) {}
    
    @Override
    public void onSuccess(Message message) {}
    
    @Override
    public void onError(Message message, RongIMClient.ErrorCode errorCode) {}
});

Push notification parameters work the same as standard messages (see above). Chatrooms don't support offline push.

ParameterTypeDescription
message[Message]The message object with content as a [MediaMessageContent] subclass. See [Message Introduction] for structure details.
pushContentStringCustom push content. Overridable by MessagePushConfig. Required for offline push on custom message types.
pushDataStringAdditional push payload. Overridable by MessagePushConfig.
callback[ISendMediaMessageCallback]Media message delivery callback

Sending Media Messages with Custom Upload​

For apps handling their own media uploads (e.g., to private servers), use sendMediaMessage with [ISendMediaMessageCallbackWithUploader]. Implement upload logic in onAttached and notify the SDK upon completion.

Interface​

RongIM.getInstance().sendMediaMessage(message, null, null, callback);

Parameters​

ParameterTypeDescription
message[Message]The message object
pushContentStringCustom push content. Overridable by MessagePushConfig. Required for offline push on custom message types.
pushDataStringAdditional push payload. Overridable by MessagePushConfig.
callback[ISendMediaMessageCallbackWithUploader]Callback for custom uploads. MediaMessageUploader references [IRongCoreCallback.MediaMessageUploader].

Example​

String path = "file://image_path";
Uri localUri = Uri.parse(path);

ConversationType conversationType = ConversationType.PRIVATE;
String targetId = "conversation ID";
ImageMessage imageMessage = ImageMessage.obtain(localUri, localUri);

Message message = Message.obtain(targetId, conversationType, imageMessage);

RongIM.getInstance().sendMediaMessage(message, null, null, new IRongCallback.ISendMediaMessageCallbackWithUploader() {
     @Override
     public void onAttached(Message message, final MediaMessageUploader uploader) {
         /* Upload to your server */
         uploadImg(imgMsg.getPicFilePath(), new UploadListener() {
             @Override
             public void onSuccess(String url) {
                 uploader.success(Uri.parse(url)); // Notify SDK with remote URL
             }

             @Override
             public void onProgress(float progress) {
                 uploader.update((int) progress); // Update progress
             }

             @Override
             public void onFail() {
                 uploader.error(); // Handle failure
             }
         });
     }

     @Override
     public void onError(Message message, RongIMClient.ErrorCode errorCode) {
         // Handle send error
     }

     @Override
     public void onSuccess(Message message) {
         // Handle success
     }

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

Sending Targeted Standard Messages​

Use sendDirectionalMessage to send messages to specific users in a group (others won't receive them). Construct the message content directly without a Message object.

Interface​

IMCenter.getInstance().sendDirectionalMessage(conversationType, targetId, messageContent, userIds, pushContent, pushData, callback);

Parameters​

ParameterTypeDescription
conversationType[ConversationType]Must be ConversationType.GROUP
targetIdStringConversation ID
messageContent[MessageContent]Message content (standard types only)
userIdsString[]Recipient user IDs
pushContentStringCustom push content. Overridable by MessagePushConfig. Required for offline push on custom message types.
pushDataStringAdditional push payload. Overridable by MessagePushConfig.
callback[IRongCallback.ISendMessageCallback]Delivery callback

Sending Targeted Media Messages​

Similar to standard messages but requires [MediaMessageContent] as content.

Interface​

IMCenter.getInstance().sendDirectionalMessage(conversationType, targetId, messageContent, userIds, pushContent, pushData, callback);

Parameters​

ParameterTypeDescription
conversationType[ConversationType]Must be ConversationType.GROUP
targetIdStringConversation ID
messageContent[MediaMessageContent]Media message content
userIdsString[]Recipient user IDs
pushContentStringCustom push content. Overridable by MessagePushConfig. Required for offline push on custom message types.
pushDataStringAdditional push payload. Overridable by MessagePushConfig.
callback[IRongCallback.ISendMediaMessageCallback]Delivery callback

Custom Push Notifications​

Configure per-message push behavior via [MessagePushConfig] (intercept messages to apply settings). This overrides sendMessage/sendMediaMessage parameters and supports:

  • Custom titles/content
  • Notification icons
  • Additional payload
  • Force-showing notification content
  • Platform-specific configurations
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 appropriate send method based on message type

MessagePushConfig Properties​

ParameterTypeDescription
disablePushTitlebooleanHide push title (iOS only; Android requires titles)
pushTitleStringHighest-priority push title. Falls back to defaults per [User Content Message Formats].
pushContentStringHighest-priority push content. Falls back to defaults.
pushDataStringAdditional push payload. Overrides sendMessage parameters.
forceShowDetailContentbooleanOverride client settings to always show notification content
iOSConfigIOSConfigiOS-specific configurations (see below)
androidConfigAndroidConfigAndroid-specific configurations (see below)
templateIdStringPush template ID matching user's language setting (configured via RongIMClient.setPushLanguageCode). Falls back to defaults if no match. Configure templates in Console > Custom Push Content. See Configuring Multilingual Push Templates.

  • iOSConfig Properties

    ParameterTypeDescription
    threadIdStringNotification grouping ID (iOS10+)
    apnsCollapseIdStringNotification replacement ID (same IDs overwrite previous notifications, iOS10+)
    richMediaUriStringCustom notification icon URL (right side). App must handle display. Requirements: 120x120px, PNG/JPG. Supported since SDK 5.2.4.
    interruptionLevelStringiOS15+: passive, active (default), time-sensitive, or critical. See APNs interruption-level. Helps bypass "Scheduled Summary" and "Focus Mode". Supported since SDK 5.6.7.

  • AndroidConfig Properties

    ParameterTypeDescription
    notificationIdStringAndroid push unique ID (defaults to messageUId). Supported by Xiaomi/Huawei.
    channelIdMiStringXiaomi notification channel ID. See Xiaomi Push Categories.
    imageUrlMiString(Deprecated) Xiaomi notification image URL (120x120px PNG/JPG). Supported since SDK 5.1.7 for MIUI 12+ (China/Global).
    channelIdHWStringHuawei notification channel ID. See Huawei Custom Channels and Android Docs.
    imageUrlHWStringHuawei notification icon URL (right side). Max 512KB, recommended 40dp x 40dp with 8dp corners. Supported since SDK 5.1.7.
    importanceHWStringHuawei notification priority: LOW (silent) or NORMAL (sound/vibration). Actual behavior depends on categoryHW or console settings. Supported since SDK 5.1.3.
    categoryHWStringHuawei message category (uppercase, e.g., IM). Requires [Huawei Category Approval] or [Special Permissions]. Overrides console category settings. See [Huawei Category Standards]. Supported since SDK 5.4.0.
    imageUrlHonorStringHonor notification icon URL (right side). Max 512KB, recommended 40dp x 40dp with 8dp corners. Supported since SDK 5.6.7.
    importanceHonorStringHonor notification category: LOW (marketing) or NORMAL (service/communication, default). Supported since SDK 5.6.7.
    typeVivoStringVIVO notification type: 0 (operational) or 1 (system). Maps to classification in [VIVO Push Docs].
    categoryVivoStringVIVO sub-category (e.g., IM). Requires matching typeVivo. Must comply with VIVO's allowed categories. Overrides console settings. See [VIVO Push Docs]. Supported since SDK 5.4.2.
    channelIdOPPOStringOPPO notification channel ID. See OPPO Push Upgrade.
    channelIdFCMStringFCM notification channel ID. App must create channel first. See Android Docs.
    collapseKeyFCMStringFCM notification group ID. Requires FCM console configuration as Notification Messages. Supported since SDK 5.1.3.
    imageUrlFCMStringFCM notification icon URL. Requires FCM console Certificate auth and Notification Messages mode. Supported since SDK 5.1.3.

Disabling Push Notifications​

By default, RC server triggers push notifications when recipients are offline (subject to app/user-level DND settings). To disable push for specific messages:

  1. Implement [MessageInterceptor] and intercept messages via interceptOnSendMessage (return true). See [Message Interception].

  2. Set disableNotification in messageConfig to true:

    message.setMessageConfig(new MessageConfig.Builder().setDisableNotification(true).build());

  3. Resend the message.

[Message Interception

Last updated on