Message Extension

The message extension feature allows you to add Key/Value-based status identifiers to the Message object. The extension information of a message can be set or updated before or after sending, and can be used to implement business requirements such as message comments, gift redemption, and order status changes.

Whether a message can carry or set extension information is determined by the canIncludeExpansion property of the Message when sending the message. This property must be set before sending the message and cannot be modified afterward. A single message can set up to 20 extension information KV pairs at a time, with a total of no more than 300 extension information KV pairs. In concurrent scenarios, if the number of KV pairs exceeds 300, the excess will be discarded.

The Key and Value extension information added to the Message object will be stored. If the historical message cloud storage feature is enabled, historical messages retrieved from the server will also carry the set extension information.

tip

• Message extension is only supported in one-to-one chat, group chat, and ultra group conversation types. It is not supported in chatrooms and system conversations.
• The 4.x SDK supports the message extension feature starting from version 4.0.3.

Implementation Approach

Taking order status change as an example, the message display status can be changed through message extension. For order confirmation:

1. When a user places an order for a specified product, the merchant needs to send an order confirmation message to the user. When sending the message, the canIncludeExpansion property in the message object can be set to expandable, and the Key and Value used to identify the order status can be set. For example, before the user confirms, a Key/Value pair can be used to indicate that the order status is "unconfirmed".
2. After the user clicks to confirm (or performs other confirmation actions) the order message, the order message status needs to be changed to "confirmed". At this time, the updateMessageExpansion method can be used to update the extension information of this message, marking it as confirmed, and changing the local display style of the message.
3. The sender obtains the status change of the specified message through the message extension status listener and displays the latest order status based on the latest extension information.

Message comments and gift redemption can be implemented with reference to the above approach:

• Gift Redemption: The message display status can be changed through message extension. For example, a gift is sent to the user, which is in an unclaimed state by default. After the user clicks, the message extension can be set to the claimed state.
• Message Comments: Comment information can be added by setting the extension information of the original message.

Enabling the Expandable Property of a Message (Before Sending Only)

After constructing a new message, call the setCanIncludeExpansion() method of the Message to enable or disable the expandable property of a message. This property must be set before sending the message.

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

Parameter	Type	Description
canIncludeExpansion	boolean	Whether the message is expandable. true: The message allows setting extension information. false: The message does not allow setting extension information. This switch state cannot be changed after the message is sent.

If the App first inserts the message locally and then sends the locally inserted message (for example, the App business requires message content to be reviewed before sending), this property must be set when inserting the message (see Insert Message). After successful local insertion, the returned message does not support modifying the expandable property switch state through setCanIncludeExpansion.

Setting Message Extension Data (Before Sending Only)

If the message has the expandable property enabled, call the setExpansion method of the Message to set the extension data. This interface can only be called before sending the message.

/** Set extension data for the message */
HashMap expansionKey = new HashMap();
expansionKey.put("key", "value");
message.setExpansion(expansionKey);

/** Send the message */
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) {

    }
});

Parameter	Type	Description
expansionMap	HashMap<String, String>	Message extension information. A maximum of 20 extension information key-value pairs can be set at a time. A single message can set up to 300 extension information pairs. Key supports a combination of uppercase and 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

In the above example, the sent message will carry the extension data set by the setExpansion method. After the message is successfully sent, the SDK will store the message and extension data in the local database.

If the message being sent already exists in the local database (see Insert Message), please note:

• （SDK ≧ 5.3.4）After successful sending, the SDK will refresh the extension data of the message in the local database.
• （SDK < 5.3.4）After successful sending, the SDK cannot refresh the extension data of the message in the local database. It is recommended that the App first sends the message and then updates the local and remote extension information by calling updateMessageExpansion. The other end can receive the updated extension data through listening.

Updating Extension Data

Call the updateMessageExpansion() method of RongIMClient to update the message extension information. Only messages with the expandable property enabled are supported. After updating the message extension information, the initiator should handle the UI data refresh in the success callback, and the other end of the conversation can receive the updated data through the message extension listener.

tip

• Each time the message extension is updated (or deleted), the SDK internally sends a signal message of type RC:MsgExMsg to the other end of the conversation. Therefore, frequent updates to the message extension will generate a large number of messages.
• Each terminal can set extension information if the upper limit is not reached; in concurrent scenarios, if the number of KV pairs exceeds 300, the excess will be discarded.
• If your business scenario requires processing on the application server, you can also set one-to-one and group chat extensions through the application server.

RongIMClient.getInstance()
        .updateMessageExpansion(
                expansionMap,
                messageUId,
                new RongIMClient.OperationCallback() {
                    @Override
                    public void onSuccess() {
                     // The initiator handles the UI data refresh after updating the extension here

                    }

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

Parameter	Type	Description
expansion	Map	The key-value pairs of message extension information to be updated, of type HashMap. Key supports a combination of uppercase and 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	The unique message ID, obtained through the getUId() method of the Message object.
callback	OperationCallback	Callback for updating extension messages

Deleting Extension Data

After sending the message, call the removeMessageExpansion method of RongIMClient to delete specific key-value pairs in the message extension information. Only messages with the expandable property enabled are supported. After deleting the message extension information, the initiator should handle the data refresh after deletion in the success callback, and the other end of the conversation can receive the notification through the message extension listener.

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

Parameter	Type	Description
keyArray	List	The list of keys to be deleted in the message extension information, of type ArrayList.
messageUId	String	The unique message ID, obtained through the getUId() method of the Message object.
callback	OperationCallback	Callback for deleting extension messages

Listening to Message Extension Data Changes

After the initiator of the message extension change calls the API to update or delete the extension data, the SDK internally sends a signal message of type RC:MsgExMsg to the other end of the conversation. The MessageExpansionListener listener will trigger the corresponding callback method after the SDK receives this signal message.

Call the setMessageExpansionListener method of RongIMClient to set the message extension listener.

RongIMClient.getInstance().setMessageExpansionListener(listener);

Parameter	Type	Description
listener	MessageExpansionListener	The message extension listener. Provides the onMessageExpansionUpdate() (when message extension information is changed) and onMessageExpansionRemove() (when message extension information is deleted) methods.