Message Extensions

The message extension feature allows adding Key/Value based status identifiers to message objects (Message). Message extension information can be set or updated before or after sending, enabling business requirements such as message comments, gift claiming, and order status changes.

tip

• Message extensions are only supported in one-to-one chats, group chats, and ultra group conversations. Not supported for chatrooms and system conversations.
• Whether a message can carry or have extension information set is determined by the canIncludeExpansion property of the Message when sending. This property must be set before sending and cannot be modified afterward.
• A single message can have up to 20 extension KV pairs set at once, with a total limit of 300 KV pairs. In concurrent scenarios, any attempts to exceed 300 KV pairs will result in the excess being discarded.
• If cloud storage for historical messages is enabled, messages retrieved from the server will include any set extension information.
• 4.x SDKs support message extensions starting from version 4.0.3.
• Each message extension update generates a built-in notification message, so frequent updates will produce a large number of messages.

Implementation Approach

Taking order status changes as an example, message display states can be modified through extensions. For order confirmation:

1. When a user places an order for a product, the merchant sends an order confirmation message. Set the canIncludeExpansion property to enable extensions and define Key/Value pairs representing order status (e.g., "unconfirmed" initially).
2. After user confirmation, update the message extension via updateMessageExpansion to reflect "confirmed" status and modify local display.
3. The sender monitors extension changes through listeners to update UI based on the latest status.

Similar approaches apply to:

• Gift claiming: Initially show as "unclaimed", update to "claimed" when received.
• Message comments: Add comments by extending the original message.

Monitoring Message Extension Changes

When extensions are updated or deleted, the SDK sends an RC:MsgExMsg signaling message to conversation peers. Receivers implement the MessageExpansionListener to handle these changes.

Set the listener after initializing IMLib SDK but before connecting to IM.

Interface

RongIMClient.getInstance().setMessageExpansionListener(listener);

Parameters

Parameter	Type	Description
listener	MessageExpansionListener	Handles onMessageExpansionUpdate() (updates) and onMessageExpansionRemove() (deletions).

Enabling Message Extensions (Pre-Send Only)

Call setCanIncludeExpansion() on the Message object before sending.

tip

• Must be set before sending.

Interface

public void setCanIncludeExpansion(boolean canIncludeExpansion) {
    this.canIncludeExpansion = canIncludeExpansion;
}

Parameters

Parameter	Type	Description
canIncludeExpansion	boolean	true: Allows extensions. false: Disallows. Cannot be changed after sending.

For locally inserted messages (e.g., pre-send moderation), set this property during insertion. The property becomes immutable afterward.

Example

TextMessage textMessage = TextMessage.obtain("content");
Message message = Message.obtain("userId", Conversation.ConversationType.PRIVATE, textMessage);
message.setCanIncludeExpansion(true);

Setting Message Extensions (Pre-Send Only)

If extensions are enabled, use setExpansion() before sending.

Parameters

Parameter	Type	Description
expansionMap	HashMap<String, String>	Key/Value pairs (max 20 per update, 300 total per message). Keys: letters, numbers, +=-_ (no Chinese, max 32 chars). Values: max 64 chars (SDK <5.2.0) or 4096 chars (SDK ≥5.2.0).

Example

HashMap expansionKey = new HashMap();
expansionKey.put("key", "value");
message.setExpansion(expansionKey);

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

Sent messages include extensions, which are stored locally. For pre-existing local messages:

• SDK ≥5.3.4: Extensions refresh automatically after sending.
• SDK <5.3.4: Manually update via updateMessageExpansion after sending. Peers receive updates via listener.

Updating Extensions

Use updateMessageExpansion() to modify extensions for eligible messages. Updates trigger UI refreshes for the sender and notifications to peers.

tip

• Each update generates an RC:MsgExMsg signal—avoid frequent updates.
• Concurrent updates beyond 300 KV pairs are discarded.
• Server-side updates are also possible via Set Chat Extensions.

:::

Interface

RongIMClient.getInstance().updateMessageExpansion(expansionMap,messageUId,callback);

Parameter Description

Parameter	Type	Description
expansion	Map	Key-value pairs for message extension updates (HashMap type). Keys support combinations of uppercase/lowercase letters, numbers, and special characters + = - _. Chinese characters are not supported. Maximum 32 characters. (SDK < 5.2.0) Value maximum 64 characters (SDK ≥ 5.2.0) Value maximum 4096 characters
messageUId	String	Unique message ID obtained via the getUId() method of the Message object.
callback	OperationCallback	Callback for message extension updates

Sample Code

RongIMClient.getInstance()
        .updateMessageExpansion(
                expansionMap,
                messageUId,
                new RongIMClient.OperationCallback() {
                    @Override
                    public void onSuccess() {
                     // Handle UI data refresh after successful extension update here

                    }

                    @Override
                    public void onError(RongIMClient.ErrorCode errorCode) {
                        Toast.makeText(
                                        getApplicationContext(),
                                        "Update failed, ErrorCode : " + errorCode.getValue(),
                                        Toast.LENGTH_LONG)
                                .show();
                    }
                });

Delete Extension Data

After sending a message, you can call the removeMessageExpansion method of RongIMClient to delete specific key-value pairs from message extensions. This only works for messages with enabled extension properties. After deletion, handle UI data refresh in the success callback, while conversation peers will receive notifications via the message extension listener.

Interface

RongIMClient.getInstance().removeMessageExpansion(keyArray, messageUId, callback);

Parameter Description

Parameter	Type	Description
keyArray	List	List of keys to be deleted from message extensions (ArrayList type).
messageUId	String	Unique message ID obtained via the getUId() method of the Message object.
callback	OperationCallback	Callback for message extension deletion