Message Extension

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

This feature enables adding Key/Value-based status identifiers to messages. Extended information can be set or updated either before or after message sending, supporting business requirements such as message commenting, gift claiming, and order status updates.

Whether a message can carry or have extended information set is determined by the canIncludeExpansion property when sending the message. This property cannot be modified after sending. Therefore, messages must be marked as expandable before sending to allow subsequent operations like adding or deleting extended information.

A single message can have up to 20 Key/Value pairs of extended information set in one operation, with a total limit of 300 pairs. In concurrent scenarios where this limit is exceeded, additional pairs will be discarded.

Message extensions (Key/Value extended information) are stored persistently. If Cloud Storage for Messages is enabled, historical messages retrieved from the server will also include any set extended information.

tip

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

Implementation Approach

Taking order status updates as an example, message display states can be modified through message extensions:

1. After a user places an order, the merchant sends an order confirmation message with canIncludeExpansion: true set, and includes an initial order status Key/Value pair in expansion, e.g., orderStatus: "Unconfirmed".
2. When the user confirms the order, the client calls the updateMessageExpansion method to update the message's extended information, changing orderStatus to "Confirmed" while updating the local message display.
3. The sender can monitor extension changes via extension change events to get real-time status updates and refresh the UI accordingly.

Similar implementations include:

• Gift claims: Initial extension state shows "Unclaimed", updating to "Claimed" when clicked, with real-time message style changes.
• Message comments: By setting or appending extended information to original messages, comment content or status can be recorded.

Enabling Message Expandability (Before Sending Only)

Before sending a message, enable message extensions via the options.canIncludeExpansion property in the sendMessage method. This must be set before sending and cannot be modified afterward.

Initial extended information can also be attached directly using the options.expansion parameter.

Sample Code

// Define target conversation - here using a group chat
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<Target ID>' }
// Instantiate message - RongIMLib.TextMessage is a built-in text message type
const message = new RongIMLib.TextMessage({ content: 'Text content' })
// Configure properties
const options = {
  // Enable message expandability
  canIncludeExpansion: true,
  // Initial extended properties
  expansion: { 
    key1: 'tom', 
    key2: 'jerry' 
  }
}

RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // On success, update message status using returned messageId
    console.log('Message sent successfully', res.data)
  } else {
    // On failure, mark message as failed using returned messageId
    console.log('Message failed to send', res.code, res.msg)
  }
})

Special Note (Electron Platform)

For apps that insert messages locally before sending (e.g., when content requires pre-send review):

• The canIncludeExpansion property must be set during insertion and cannot be modified afterward.
• When sending, use the inserted message's messageId in sendMessage and pass extended information via options.expansion. The SDK will synchronize extended data to the local database upon successful sending.

Updating Message Extensions

Call updateMessageExpansion to update extended information for a specific message. Recipients can monitor changes via extension update events.

tip

• Only supported in one-to-one and group chats.
• Each update generates a built-in notification message - frequent calls may impact performance.
• Only works for messages originally sent with canIncludeExpansion: true.

Interface

RongIMLib.updateMessageExpansion(expansion, message)

Parameters

Parameter	Type	Required	Description
expansion	Record<string, string>	Yes	Key/Value pairs to update: Keys support letters, numbers, and + = - _, max 32 chars. (SDK < 5.3.0) Values max 64 chars. (SDK ≥ 5.3.0) Values max 4096 chars.
message	IAReceivedMessage	Yes	Target message object (from live or historical messages)

Sample Code

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)
  }
})

Deleting Message Extensions

Call removeMessageExpansionForKey to delete specific extension keys.

Interface

RongIMLib.removeMessageExpansionForKey(keys, message)

Parameters

Parameter	Type	Required	Description
keys	string[]	Yes	Array of keys to delete
message	IAReceivedMessage	Yes	Target message object

Sample Code

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

Monitoring Extension Notifications

Monitor the Events.EXPANSION event to capture message extension changes:

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