Forward messages
Overview
ZIM SDK supports two forms of message forwarding:
- Forwarding combined messages.
- Forwarding messages one by one.
Forwarding combined messages
- Only ZIM SDK version 2.14.0 and above supports sending and receiving combined messages.
- If the SDK version of the receiving end is between [2.0.0, 2.14.0), the receiving end can receive combined messages, but the message type will be displayed as unknown and the message content cannot be obtained. To obtain this message, please upgrade the SDK to version 2.14.0 or above.
- If the SDK version of the receiving end is version 1.x.x, it cannot receive combined messages.
Send combined messages
The steps to send combined messages are as follows:
- Construct the combined message body using the ZIMCombineMessage object. The parameters include:
| Parameter | Type | Required | Description |
|---|
| title | string | Yes | The title of the combined message, with a default maximum length of 20 bytes. If you need to configure it, please contact ZEGOCLOUD technical support. |
| summary | string | Yes | The summary of the combined message, with a default maximum length of 100 bytes. If you need to configure it, please contact ZEGOCLOUD technical support. |
| messageList | ZIMMessage[] | Yes | The original message list to be combined and forwarded. It does not support merging and forwarding messages of signaling, barrage, recall, and system types, and does not support merging and forwarding unsuccessful messages. |
ZIM SDK supports including other combined messages in a combined message.
- Call the sendMessage interface to send the combined message. For more information about this operation, see Send & Receive messages - Send messages.
The following is an example code for a user to send a combined message in a one-on-one conversation:
// Send a combined message in a one-on-one conversation
ZIMConversationType type = PEER; // Conversation type, value: one-on-one: 0, room: 1, group: 2
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// The original message list to be combined and forwarded, which can be obtained from the message history
ArrayList<ZIMMessage> messageList = new ArrayList<>();
messageList.add(message1);
messageList.add(message2);
ZIMCombineMessage combineMessage = new ZIMCombineMessage("Title", "Summary", messageList);
zim.sendMessage(combineMessage,"conv_id", type, config, new ZIMMessageSentCallback() {
@Override
public void onMessageAttached(ZIMMessage zimMessage) {
// Developers can use this callback to listen for whether the message is ready to be sent. Only messages that pass the local basic parameter check will trigger this callback, otherwise errors will be thrown through the onMessageSent callback.
}
@Override
public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
// Developers can use this callback to listen for whether the message is sent successfully.
}
});
1
// Send a combined message in a one-on-one chat session
ZIMConversationType type = ZIMConversationTypePeer; // Conversation type, values: one-on-one: 0, room: 1, group: 2
ZIMMessageSendConfig *config = [[ZIMMessageSendConfig alloc] init];
// The original message list to be combined and forwarded, can be obtained from the message history
NSMutableArray<ZIMMessage *> *messageList = [NSMutableArray array];
[messageList addObject:message1];
[messageList addObject:message2];
ZIMCombineMessage *combineMessage = [[ZIMCombineMessage alloc] initWithTitle:@"Title" summary:@"Summary" messages:messageList];
[zim sendMessage:combineMessage conversationId:@"conv_id" type:type config:config callback:^(ZIMMessage *zimMessage, ZIMError *error) {
if (error) {
// Developers can use this callback to listen for whether the message was sent successfully.
}
}];
1
// Send a combined message in a one-on-one chat session
ZIMConversationType type = ZIM_CONVERSATION_TYPE_PEER; // Conversation type, values: one-on-one: 0, room: 1, group: 2
ZIMMessageSendConfig config;
// The original message list to be combined and forwarded, can be obtained from the message history
std::vector<std::shared_ptr<ZIMMessage>> messageList;
messageList.push_back(message1);
messageList.push_back(message2);
std::shared_ptr<ZIMCombineMessage> combineMessage = std::make_shared<ZIMCombineMessage>("Title", "Summary", messageList);
if (message) {
// Developers can use this callback to listen for whether the message is ready to be sent. Only messages that pass the local basic parameter check will trigger this callback, otherwise errors will be thrown through the onMessageSent callback.
}),
[=](std::shared_ptr<zim::ZIMMessage> message, zim::ZIMError errorInfo) {
// Developers can use this callback to listen for whether the message is sent successfully.
if (errorInfo.code == zim::ZIMErrorCode::ZIM_ERROR_CODE_SUCCESS) {
}
});
1
// Send a combined message in a one-on-one chat session
try {
// Conversation type, values are one-on-one: peer, room: room, group: group
ZIMConversationType type = ZIMConversationType.peer;
ZIMMessageSendConfig config = ZIMMessageSendConfig();
// The original message list to be combined and forwarded, which can be obtained from the message history
List<ZIMMessage> messageList = [message1,message2];
ZIMCombineMessage combineMessage = ZIMCombineMessage(title: 'Title', summary: 'Summary', messageList: messageList);
ZIMMessageSentResult result = await ZIM.getInstance()!.sendMessage(combineMessage, 'conv_id', type, config);
// Message sent successfully
} on PlatformException catch (onError){
onError.code;//Handle according to the error code table
onError.message;//Error message
}
1
// Send a combined message in a one-to-one chat.
var toConversationID = ''; // The ID of the other user.
var conversationType = 0; // The conversation type. Valid values: 0: one-to-one chat; 1: voice chatroom; 2: group chat.
var config = {
priority: 1, // Specify the message priority. Valid values: 1 (default): low; 2: medium; 3: high.
};
var messageCombineObj = {
type: 31,
title: 'Title', // The title of the combined message.
summary: 'Summary' , // The summary of the combined message.
messageList: [message1, message2], // The list of messages to be combined and forwarded, which can be obtained from historical messages.
};
var notification = {
onMessageAttached: function(message) {
// To-do: loading.
}
}
zim.sendMessage(messageCombineObj, toConversationID, conversationType, config, notification)
.then(function ({ message }) {
// Sending succeeded.
})
.catch(function (err) {
// Sending failed.
});
1
Receive combined messages
The callback interface for receiving combined messages is the same as the callback interface for receiving normal messages. Please refer to Send & Receive messages - Receive messages for the specific interface.
The receive message callback only returns the title, summary, and combination ID of the combined message. If you need to know the content of the combined message, please refer to View Combined Message Details.
The following is an example code for a user to receive combined messages in a one-on-one conversation:
// User receives combined messages in a one-on-one conversation
@Override
public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList,
ZIMMessageReceivedInfo info, String fromUserID) {
for (ZIMMessage message : messageList) {
if (message.getType() == ZIMMessageType.COMBINE){
// combined message
}
}
}
1
// User receives combined messages in a one-on-one conversation
- (void)zim:(ZIM *)zim
peerMessageReceived:(NSArray<ZIMMessage *> *)messageList
info:(ZIMMessageReceivedInfo *)info
fromUserID:(NSString *)fromUserID {
for (ZIMMessage *message in messageList) {
if ([message type] == ZIMMessageTypeCombine) {
// combined Message
}
}
}
1
// User receives combined messages in a one-on-one conversation
void onPeerMessageReceived(ZIM& zim, std::vector<ZIMMessage>& messageList,
ZIMMessageReceivedInfo info,
std::string fromUserID) {
for (ZIMMessage& message : messageList) {
if (message.type == ZIMMessageType::ZIM_MESSAGE_TYPE_COMBINE) {
// combined Message
}
}
}
1
// User receives a combined message in a one-on-one chat session
ZIMEventHandler.onReceivePeerMessage = (ZIM zim, List<ZIMMessage> messageList, String fromUserID){
for(ZIMMessage message in messageList){
if(message.type == ZIMMessageType.combine){
// combined message
}
}
};
1
// The user receives a combined message in a one-to-one chat.
zim.on('peerMessageReceived', function (zim, { messageList, fromConversationID }) {
console.log(messageList, fromConversationID);
messageList.forEach(function (msg) {
// The `Combine` message is received.
if (msg.type == 31) {
}
})
});
1
View combined message details
Operations on a combined message, for example, listening, adding, and historical message pulling, return only the title, summary, and ID of the combined message. To view sub-messages contained in the combined message, call the queryCombineMessageDetail operation.
The result is returned in the ZIMCombineMessageDetailQueriedCallback callback.
public abstract void queryCombineMessageDetail(ZIMCombineMessage message,
ZIMCombineMessageDetailQueriedCallback callback);
1
- (void)queryCombineMessageDetailByMessage:(ZIMCombineMessage *)message
callback:(ZIMCombineMessageDetailQueriedCallback)callback
1
virtual void
queryCombineMessageDetail(std::shared_ptr<ZIMCombineMessage> &message,
const ZIMCombineMessageDetailQueriedCallback &callback) = 0;
1
Future<ZIMCombineMessageDetailQueriedResult> queryCombineMessageDetail(ZIMCombineMessage message);
1
queryCombineMessageDetail(message: ZIMCombineMessage): Promise<ZIMCombineMessageDetailQueriedResult>
1
| Parameter | Type | Required | Description |
|---|
| message | ZIMCombineMessage | Yes | The combined message to be queried. |
zim.queryCombineMessageDetail(combineMessage, new ZIMCombineMessageDetailQueriedCallback() {
@Override
public void onCombineMessageDetailQueried(ZIMCombineMessage message, ZIMError error) {
// View the combined message, the specific sub-messages are in the messageList of the message in the callback.
}
});
1
[zim queryCombineMessageDetailByMessage:combineMessage callback:^(ZIMCombineMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
// View the combined message, the specific sub-messages are in the messageList of the message in the callback.
}];
1
zim_->queryCombineMessageDetail(combineMessage, [=](const std::shared_ptr<ZIMCombineMessage> &message, ZIMError &errorInfo) {
// View the combined message, the specific sub-messages are in the messageList of the message in the callback.
}];
1
try {
// Conversation type, values are one-on-one: peer, room: room, group: group
ZIMCombineMessageDetailQueriedResult result = await ZIM.getInstance()!.queryCombineMessageDetail(combineMessage);
// View the combined message, the specific sub-messages are in the messageList of the message in the callback.
result.message.messageList;
// Message sent successfully
} on PlatformException catch (onError){
onError.code;//Handle according to the error code table
onError.message;//Error message
}
1
zim.queryCombineMessageDetail(message)
.then(function (message) {
// Operation succeeded. The list of sub-messages of the combined message is updated on the UI.
// The detailed sub-messages are contained in the messageList of the message in the callback.
console.log(message.messageList)
})
.catch(function (err) {
// Operation failed.
});
1
If one of the sub-messages is a combined message, you need to call the queryCombineMessageDetail operation to obtain the sub-messages of the combined message. If there are multiple nested combined messages, you need to call this operation multiple times accordingly.
Forward messages one by one
Forwarding messages one by one is essentially sending messages that have been successfully sent as parameters to other conversations. It uses the same interface as sending normal messages. Developers can refer to Send & Receive messages - Send messages for details of this interface.
