Message Extensions

The message extension feature allows adding Key/Value state identifiers to message objects (RCMessage). Extension information can be set or updated both before and after message sending, enabling business requirements such as message comments, gift redemption, and order status updates.

tip

• Whether a message can carry or have extensions set is determined by the canIncludeExpansion property of RCMessage during sending. This property must be configured before sending and cannot be modified afterward.
• A single message can have up to 20 extension KV pairs set per operation, with a total limit of 300 KV pairs. In concurrent scenarios, any extensions exceeding 300 will be discarded.
• If cloud message history storage is enabled, historical messages retrieved from the server will include any previously set extensions.
• Each extension update generates a built-in notification message, and frequent updates may produce significant message volume.

Monitoring Message Processing

Set the setRCUltraGroupMessageChangeDelegate delegate to monitor remote users' modifications to message extensions:

1. Configure the setRCUltraGroupMessageChangeDelegate: delegate:

[[RCChannelClient sharedChannelManager] setRCUltraGroupMessageChangeDelegate:self];

2. Implement the onUltraGroupMessageExpansionUpdated: message extension update delegate method:

/*!
 Message extension updates and deletions

 @param messages Message collection
 */
- (void)onUltraGroupMessageExpansionUpdated:(NSArray<RCMessage*>*)messages {

}

Setting Message Extensions Before Sending

After constructing a new message, configure the canIncludeExpansion property of RCMessage to enable or disable extension capabilities for that message.

tip

• The canIncludeExpansion property must be set before message sending.

Sample Code

RCTextMessage *txt = [RCTextMessage messageWithContent:text];

RCMessage *msg = [[RCMessage alloc] initWithType:ConversationType_ULTRAGROUP targetId:self.targetId direction:(MessageDirection_SEND) messageId:-1 content:txt];
msg.canIncludeExpansion = YES;
msg.expansionDic = @{@"key1":@"value1",@"key2":@"value2"};

[[RCIMClient sharedRCIMClient] sendMessage:msg pushContent:nil pushData:nil successBlock:^(RCMessage *successMessage) {

} errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {

}];

Updating Message Extensions

Use the updateUltraGroupMessageExpansion: method to update message extensions, which only works for messages with enabled extension capabilities. After updating, the initiator should handle UI data refresh in the success callback, while conversation peers receive updates through the message extension listener.

Method Prototype

//Update message extensions
- (void)updateUltraGroupMessageExpansion:(NSString *)messageUId
                            expansionDic:(NSDictionary<NSString *, NSString *> *)expansionDic
                                 success:(void (^)(void))successBlock
                                   error:(void (^)(RCErrorCode status))errorBlock

Parameter Description

Parameter	Type	Description
expansionDic	NSDictionary	Key-value pairs for message extension updates. Keys support alphanumeric characters and special symbols + = - _, excluding Chinese characters. Maximum 32 characters. (SDK < 5.2.0) Value limit: 64 characters (SDK ≧ 5.2.0) Value limit: 4096 characters
messageUId	NSString	Message messageUId.
successBlock	Block	Success callback.
errorBlock	Block	Failure callback. status contains error codes [RCErrorCode]

Sample Code

[[RCChannelClient sharedChannelManager] updateUltraGroupMessageExpansion:message.messageUId expansionDic:dic success:^{
           
} error:^(RCErrorCode status) {
          
}];

Deleting Message Extensions

After message sending, call removeUltraGroupMessageExpansion: to delete specific key-value pairs from message extensions, applicable only to messages with enabled extension capabilities. Upon successful deletion, handle UI data refresh in the callback while conversation peers receive notifications through the extension listener.

Method Prototype

//Delete message extensions
- (void)removeUltraGroupMessageExpansion:(NSString *)messageUId
                                keyArray:(NSArray *)keyArray
                                 success:(void (^)(void))successBlock
                                   error:(void (^)(RCErrorCode status))errorBlock

Parameter Description

Parameter	Type	Description
keyArray	NSArray	List of keys to be deleted from message extensions.
messageUId	NSString	Message messageUId.
successBlock	Block	Success callback.
errorBlock	Block	Failure callback. status contains error codes [RCErrorCode].

Sample Code

[[RCChannelClient sharedChannelManager] removeUltraGroupMessageExpansion:keyArray messageUId:messageUId success:^{

} error:^(RCErrorCode status) {

}];