Message Extension

The message extension feature allows for adding, modifying, or deleting extended information from sent messages.

The message extension feature can add Key/Value-based status identifiers to messages. The extended information of a message can be set or updated before or after sending, enabling business requirements such as message comments, gift redemption, and order status changes.

Whether a message can carry or have extended information set is determined by the canIncludeExpansion property when the message is sent. This property cannot be modified after sending. Therefore, the message must be set as expandable before sending to allow for the addition, deletion, or other operations on the extended information of that message.

A single message can have a maximum of 20 Key/Value pairs of extended information set at one time, with a total of no more than 300 Key/Value pairs. In concurrent scenarios, if more than 300 pairs are set, the excess pairs will be discarded.

Message extensions (Key, Value extended information) are stored. If the message cloud storage feature is enabled, historical messages retrieved from the server will also carry the set extended information.

tip

Message extensions are only supported in one-to-one chat, group chat, and ultra group conversations. They are not supported in chatrooms and system conversations.

Implementation Approach

Taking order status changes as an example, message extensions can be used to alter the display status of messages. For instance, when confirming an order:

1. After 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 can be set to allow extensions, and a Key/Value pair can be set to indicate the order status. For example, before the user confirms, a Key/Value pair can represent the order status as "Unconfirmed."
2. After the user clicks to confirm (or performs another confirmation action) the order message, the order message status needs to change to "Confirmed." At this point, the updateMessageExpansion method can be used to update the extended information of this message, marking it as confirmed, and changing the local display style of the message.
3. The sender can monitor the message extension status changes through a listener, obtaining the status changes of the specified message and displaying the latest order status based on the most recent extended information.

Message comments and gift redemptions can be implemented following the above approach:

• Gift Redemption: The message display status can be changed using message extensions. For example, when sending a gift to a user, the default status is "Unredeemed." After the user clicks to redeem, the message extension can be set to "Redeemed."
• Message Comments: Comments can be added by setting the extended information of the original message.

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

Before sending a new message, the expandable property of the message can be enabled or disabled via the options.canIncludeExpansion property in SendMessage. This property must be set before sending the message.

You can also set the extended information data options.expansion before sending the message. In the example below, the sent message will carry the extended information data from the expansion property.

// Define the target conversation for message delivery, here defining a group conversation
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<Target ID>' }
// Instantiate the message to be sent, RongIMLib.TextMessage is a built-in text message type
const message = new RongIMLib.TextMessage({ content: 'Text content' })
// Configure properties
const options = {
  // Enable the expandable property of the message
  canIncludeExpansion: true,
  expansion: { key1: 'tom', key2: 'jerry' }
}

RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // Message sent successfully, you can change the status of the message in the list to "Sent" based on the messageId field in the response.
    console.log('Message sent successfully', res.data)
  } else {
    // Message failed to send, you can change the status of the message in the list to "Failed" based on the messageId field in the response.
    console.log('Message failed to send', res.code, res.msg)
  }
})

For the Electron platform, there may be scenarios where the app first inserts a message locally and then sends the locally inserted message (e.g., when the app requires message content review before sending). If you need to use the message extension feature, please note the following:

• When inserting a message, the canIncludeExpansion property must be set. Once the message is successfully inserted, the expandable property cannot be modified.
• When sending, the local message ID (messageId) must be obtained from the successfully inserted message (IAReceivedMessage). After successful sending, the SDK will refresh the extended data of the message in the local database based on the extended data in SendMessage's options.expansion.

Updating Message Extended Information

Call updateMessageExpansion to set or update message extended information. The recipient can be notified of the updated extended data through a listener.

• Only supported in one-to-one and group chat conversations, not in chatrooms.
• Each time the message extension is set, a built-in notification message will be generated. Frequent setting of extensions will result in a large number of messages.
• Only when the canIncludeExpansion value is set to true when sending the message, can the message be extended.

RongIMLib.updateMessageExpansion({ key1: 'val1', key2: 'val2' }, message).then(res => {
  if (res.code === 0) {
    console.log(res.code, 'Update successful')
  } else {
    console.log(res.code, res.msg)
  }
})

Parameter	Type	Description
expansion	Map	The Key/Value pairs of message extended information to be updated, type is HashMap. Key supports uppercase and lowercase letters, numbers, and special characters + = - _. Chinese characters are not supported. Maximum of 32 characters. （SDK < 5.3.0）Value maximum of 64 characters （SDK ≧ 5.3.0）Value maximum of 4096 characters
message	IAReceivedMessage	The message instance obtained from IMLib by receiving online messages or pulling historical messages.

Deleting Message Extended Information

Call removeMessageExpansionForKey to delete message extended information.

RongIMLib.removeMessageExpansionForKey(['key1', 'key2'], messsage).then(res => {
  if (res.code === 0) {
    console.log(res.code, 'Deletion successful')
  } else {
    console.log(res.code, res.msg)
  }
})

Parameter	Type	Description
keyArray	List	The list of keys to be deleted from the message extended information, type is ArrayList.
message	IAReceivedMessage	The message instance obtained from IMLib by receiving online messages or pulling historical messages

Listening to Message Extension Notifications

You can listen to the Events.EXPANSION event to capture notifications of changes in message extended information.

RongIMLib.addEventListener(RongIMLib.Events.EXPANSION, ({ updatedExpansion, deletedExpansion }) => {
  console.log('Extended information updated：', updatedExpansion);
  console.log('Extended information deleted：', deletedExpansion);
})