logo
In-app Chat
SDK Error Codes
Powered Byspreading
On this page

Send and receive messages


ZEGOCLOUD's In-app conversation (the ZIM SDK) provides the capability of message management, allowing you to send and receive one-to-one, group, in-room messages, query message history, delete messages, and more. With the message management feature, you can meet different requirements of various scenarios such as social entertainment, online shopping, online education, interactive live streaming, and more.

This document describes how to send and receive messages with the ZIM SDK.

Message types

Message TypeDescriptionFeature and Scenario
ZIMCommandMessage(2)The signaling message whose content can be customized. A signaling message cannot exceed 5 KB in size, and up to 10 signaling messages can be sent per second per client.

Signaling messages, unable to be stored, are applicable to signaling transmission (for example, co-hosting, virtual gifting, and course materials sending) in scenarios with a higher concurrency, such as chat rooms and online classrooms.

API: sendMessage

ZIMBarrageMessage(20)On-screen comments in a chat room. An on-screen comment cannot exceed 5 KB in size, and there is no number limit on comments that can be sent per second per client.

On-screen comments, unable to be stored are usually unreliable messages that are sent at a high frequency and can be discarded.

A high concurrency is supported, but reliability cannot be guaranteed.

API: sendMessage

ZIMTextMessage(1)The text message. A text message cannot exceed 32 KB in size, and up to 10 text messages can be sent per second per client.

Text messages are reliable, in order, and able to be stored as historical messages. (For the storage duration, please refer to Pricing - Plan Fee - Plan Differences).
It is applicable to one-to-one chats, group chats, and on-screen comments in chat rooms. After a room is disbanded, messages in it are not stored.

  • Images, files, audio, video: Typically used for sending rich media messages.
  • Custom message: Typically used for sending messages such as polls, chain messages, video cards, etc.
  • Multi-item Message: Typically used for sending a message including images and text.

API: sendMessagereplyMessage

ZIMMultipleMessage(10)Multi-item message, a message that can include multiple texts, up to 10 images, 1 file, 1 audio, 1 video, and 1 custom message.
Note
  • The total number of items should not exceed 20.
  • The size and format restrictions for images, audio, files, and videos are the same as those for the corresponding rich media message types.
ZIMImageMessage(11)Image message. Applicable formats includes JPG, PNG, BMP, TIFF, GIF, and WebP. The maximum size is 10 MB. Up to 10 image messages can be sent per second per client.
ZIMFileMessage(12)File Message. A file message contains a file of any format and cannot exceed 100 MB in size. Up to 10 file messages can be sent per second per client.
ZIMAudioMessage(13)Audio message. An audio message contains an MP3 or M4A audio of up to 300 seconds and cannot exceed 6 MB in size. Up to 10 audio messages can be sent per second per client.
ZIMVideoMessage(14)A video message contains an MP4 or MOV video and cannot exceed 100 MB in size. Up to 10 video messages can be sent per second per client.
Note
To retrieve the width and height of the first video frame after a video is successfully sent, the video must be encoded in H.264 or H.265.
ZIMCombineMessage(100)For combined messages, there is no limit on message size, and the sending frequency of a single client is limited to 10 times/second.
ZIMCustomMessage(200)You can customize the message type and parse the message without using the ZIM SDK.

Send/Receive regular messages

Regular messages refer to the messages of the following message types: ZIMTextMessage and ZIMBarrageMessage.

Warning
  • To receive event callbacks (receive messages, get connection status, and receive a notification when Token is about to expire, etc.), you can set up the setEventHandler method and listen for related events.
  • When receiving messages, you need to determine the message is a Text message ZIMTextMessage or a Command message ZIMCommandMessage because these two message types are based on the basic message class ZIMMessage. You need to convert the basic message class to a concrete message type and then retrieve the message content from the message field.
  • When a message is received, it can be sorted using the message's orderKey. The larger the orderKey, the newer the message. And the number of unread messages will be updated automatically upon receiving.

Send messages

The following process shows how Client A sends messages to Client B:

  1. Client A and Client B create their own ZIM SDK instances, and set up an event handler setEventHandler to listen for the callback on the result of message sending onPeerMessageReceived.
  2. Client A and Client B log in to the ZIM SDK.
  3. Client A calls the sendMessage method, and set the converversationType to ZIMConversationTypePeer to send a one-to-one message to Client B.
  4. Client B listens for the onPeerMessageReceived callback to receive Client A's messages.
Warning

You can't send messages to yourself by calling the sendMessage method (when toConversationID = your ID). If you did so, the error code 6000001 will return.

SampleCode
// Send a text message to a one-to-one conversation
String toConversationID = "xxxx1";

ZIMTextMessage zimMessage = new ZIMTextMessage();
zimMessage.message = "Message content";

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set the message priority.
config.priority = ZIMMessagePriority.LOW;
// Set up the configurations of the offline notifications.
// Offline push configuration of room messages is not supported. If you need to send room offline messages, please contact ZEGOCLOUD technical support team to activate relevant permissions.
ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "Offline notification title";
pushConfig.content= "Offline notification content";
pushConfig.extendedData = "Extension info of the offline notification";
config.pushConfig = pushConfig;

ZIMConversationType type = ZIMConversationType.Peer;

zim.sendMessage(zimMessage, toConversationID, type, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage zimMessage) {
    // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.
    }

    @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
    // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.
    }
});
1
Copied!

Receive messages

Note
SampleCode
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromUserID) {
        // Callback for receiving one-to-one messages. 
        for (ZIMMessage zimMessage : messageList) {
           if (zimMessage instanceof ZIMTextMessage) {
                ZIMTextMessage zimTextMessage = (ZIMTextMessage) zimMessage;
                Log.e(TAG, "The text message you received:"+ zimTextMessage.message);
           } else if (zimMessage instanceof ZIMCommandMessage) {
                ZIMCommandMessage zimCommandMessage = (ZIMCommandMessage) zimMessage;
                Log.e(TAG, "The signaling message you received:"+ zimCommandMessage.message);
           }    
        }
    }

    @Override
    public void onGroupMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromGroupID) {
        // Callback for receiving group messages. 
        for (ZIMMessage zimMessage : messageList) {
           if (zimMessage instanceof ZIMTextMessage) {
                ZIMTextMessage zimTextMessage = (ZIMTextMessage) zimMessage;
                Log.e(TAG, "The text message you received:"+ zimTextMessage.message);
           } else if (zimMessage instanceof ZIMCommandMessage) {
                ZIMCommandMessage zimCommandMessage = (ZIMCommandMessage) zimMessage;
                Log.e(TAG, "The signaling message you received:"+ zimCommandMessage.message);
           }    
        }
    }

    @Override
    public void onRoomMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromRoomID) {
        // Callback for receiving in-room messages. 
        for (ZIMMessage zimMessage : messageList) {
           if (zimMessage instanceof ZIMTextMessage) {
                ZIMTextMessage zimTextMessage = (ZIMTextMessage) zimMessage;
                Log.e(TAG, "The text message you received:"+ zimTextMessage.message);
           } else if (zimMessage instanceof ZIMCommandMessage) {
                ZIMCommandMessage zimCommandMessage = (ZIMCommandMessage) zimMessage;
                Log.e(TAG, "The signaling message you received:"+ zimCommandMessage.message);
           }    
        }
    }
});
1
Copied!

Send/Receive rich media content

The ZIM SDK now supports sending and receiving messages of different rich media types, such as images, audio, video, and files. To send and receive rich media content, refer to the following:

  1. To send rich media content after login, the message type (image, file, audio, or video) first and the conversation type (one-to-one, room, group) should be specified.
  2. To receive rich media content, the recipient should listen for relevant event callbacks related to the conversation type after logging in. This will enable them to receive message events and download the content locally.

Send rich media content

To send rich media content after login, call the sendMessage method, and specify the message type (image, file, audio, video), the conversation type (one-to-one, room, group), and message related configurations as needed.

Warning
  • When sending rich media content, the file path to be sent must be in UTF-8 encoding format.
  • To send rich media content to a room/group, the sender must be in the room/group.
Image
File
Audio
Video
// Send rich media content in one-to-one conversation - Send an image:
ZIMImageMessage message = new ZIMImageMessage("/storage/emulated/0/Android/data/packagename/picture/xxx.jpg");
// If a network URL is entered here, the SDK will pass through the path without ZIM background service processing. If both the network URL and the local path are entered, the SDK will prioritize the network URL that you want to use.
message.setLargeImageDownloadUrl("url");
message.setFileDownloadUrl("url");
message.setThumbnailDownloadUrl("url");
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set message priority. 
config.priority = ZIMMessagePriority.LOW;
// Set up the configurations of the offline notifications.
ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "Offline notification title";
pushConfig.content= "Offline notification content";
pushConfig.extendedData = "Extension info of the offline notification";
config.pushConfig = pushConfig;

zim.sendMessage(message, toConversationID, ZIMConversationType.PEER, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
     // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.。                    
    }

    @Override
    public void onMessageAttached(ZIMMessage message){
    
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize, ) {
         // You can use this callback to monitor whether the message is sent successfully.              
    }
});
1
Copied!
// Send rich media content in one-to-one conversation - Send a file:
ZIMFileMessage message = new ZIMFileMessage("/storage/emulated/0/Android/data/packagename/picture/xxx.zip");
// If a network URL is provided here, the SDK will pass through the path directly without processing it via the ZIM backend services. When both a network URL and a local path are provided, the SDK will prioritize using the network URL. 
message.setFileDownloadUrl("url");
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
config.priority = ZIMMessagePriority.HIGH;
zim.sendMessage(message, conversationID, ZIMConversationType.PEER, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
               
    }

    @Override
    public void onMessageAttached(ZIMMessage message){
    
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
               
    }
});
1
Copied!
// Send rich media content in one-to-one conversation - Send an audio:
ZIMAudioMessage message = new ZIMAudioMessage("/storage/emulated/0/Android/data/packagename/picture/xxx.mp3", 300); // 300 is only for example, the unit is second.

// If a network URL is provided here, the SDK will pass through the path directly without processing it via the ZIM backend services. When both a network URL and a local path are provided, the SDK will prioritize using the network URL. 
message.setFileDownloadUrl("url");
ZIMMessageSendConfig config = new ZIMMessageSendConfig();

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
config.priority = ZIMMessagePriority.HIGH;
zim.sendMessage(message, conversationID, ZIMConversationType.PEER, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
               
    }
    
    @Override
    public void onMessageAttached(ZIMMessage message){
    
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
               
    }
});
1
Copied!
// Send rich media content in one-to-one conversation - Send a video:
ZIMVideoMessage message = new ZIMVideoMessage("/storage/emulated/0/Android/data/packagename/picture/xxx.mp4", 300);//这里单位是秒

// 如果此处填了网络 URL,SDK 则会透传该路径,而不会经过 ZIM 后台服务处理,同时填入网络 URL 与本地路径,SDK 会优先认为用户想要使用网络 URL
message.setFileDownloadUrl("url");
message.videoFirstFrameDownloadUrl("url");
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
config.priority = ZIMMessagePriority.HIGH;
zim.sendMessage(message, conversationID, ZIMConversationType.PEER, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
               
    }
   
    @Override
    public void onMessageAttached(ZIMMessage message){
    
    }

    @Override
    public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
               
    }
});
1
Copied!

Callback for the sending progress of rich media content

You will be notified of the sending progress of rich media content through the callback onMediaUploadingProgress.

Untitled
void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize);
1
Copied!

Among which:

  • message: The content of the message being sent.
  • currentFileSiz: The size of the message that has been sent.
  • totalFileSize: The overall size of the message sent.

Receive rich media content

To receive the rich media content messages, do the following: After logging in, users should listen for the following callbacks based on the conversation type (one-to-one, room, group): onPeerMessageReceived, onRoomMessageReceived, onGroupMessageReceived, to receive the events of rich media messages. From the events, the URL of rich media content can be obtained directly.

If you want to download the rich media content locally, call the downloadMediaFile method.

When downloading rich media content, you need to specify the file type of the corresponding media messages first.

  • Image messages: You can choose to download the original file, large view, or thumbnail.
  • Files/Audio messages: Only original files/audio files can be downloaded.
  • Video messages: You can choose to download the original video file and the thumbnail of the first frame of the video.
SampleCode
// Receive rich media content in one-to-one conversation - Receive images:
@Override
public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromUserID) {
    super.onPeerMessageReceived(zim, messageList, info, fromUserID);
    
    ZIMMediaDownloadConfig config = new ZIMMediaDownloadConfig();

    for (ZIMMessage message : messageList) {
        // You can tell by the Type which kind of message you are receiving. 
        if (message.getType() == ZIMMessageType.IMAGE) {
            // Receive the image
            ZIMImageMessage imageMessage = (ZIMImageMessage) message;
            zim.downloadMediaFile(imageMessage, ZIMMediaFileType.ORIGINAL_FILE, config, new ZIMMediaDownloadedCallback() {

                @Override
                public void onMediaDownloaded(ZIMMessage message, ZIMError errorInfo) {
                    // The callback for download completion.
                }

                @Override
                public void onMediaDownloadingProgress(ZIMMessage message, long currentFileSize, long totalFileSize) {
                    // The download progress 
                }
            });
        } else if (message.getType() == ZIMMessageType.VIDEO) {
            // Receive the video
            ZIMVideoMessage videoMessage = (ZIMVideoMessage) message;
        } else if (message.getType() == ZIMMessageType.AUDIO) {
            // Receive the audio
            ZIMAudioMessage audioMessage = (ZIMAudioMessage) message;
        } else if (message.getType() == ZIMMessageType.FILE) {
            // Receive the file
            ZIMFileMessage fileMessage = (ZIMFileMessage) message;
        }
    }
}
1
Copied!

Callback for the downloading progress of rich media content

You will be notified of the downloading progress of rich media content through the callback ZIMMediaDownloadingProgress.

Untitled
void onMediaDownloadingProgress(ZIMMessage message, long currentFileSize, long totalFileSize);
1
Copied!

Among which:

  • message: The message content you are downloading.
  • currentFileSize: The size of messages that have been downloaded.
  • totalFileSize: The overall size of the download message.

Send/Receive signaling messages

The ZIM SDK now supports you to send and receive signaling messages. To do that, you can call the ZIMCommandMessage to define the message type you want to send, for example, your location information.

Note

This message type does not support offline push and local storage.

The following shows how to send custom messages to a specified user.

Send signaling messages

SampleCode
// Send a signaling message to a user
String userID = "xxxx";

ZIMCommandMessage zimCustomMessage = new ZIMCommandMessage();
zimCustomMessage.message = new byte[]{0x1,0x2,0x1,0x2};

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set message priority.
config.priority = ZIMMessagePriority.LOW;
// Configure for offline notification
// For a room conversation, offline notification is not supported. To use it, contact ZEGOCLOUD Technical Support to enable the feature first.
ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "Offline notification title";
pushConfig.content= "Offline notification content";
pushConfig.extendedData = "Extra information for the offline notification";
config.pushConfig = pushConfig;

// Send a one-to-one message.
ZIMConversationType type = ZIMConversationType.Peer;

// Send a group message.
// ZIMConversationType type = ZIMConversationType.Gourp;

// Send a in-room message.
// ZIMConversationType type = ZIMConversationType.Room;

zim.sendMessage(zimCustomMessage, toConversationID, type, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage zimMessage) {
        // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.
    }

    @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
        // You can listen for the callback to know whether the message is sent successfully.
    }
});
1
Copied!

Receive signaling messages

SampleCode
// Receive signaling messages.
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromUserID) {
        // Callback on the command message received.
        for (ZIMMessage zimMessage : messageList) {
            if (zimMessage instanceof ZIMCommandMessage) {
                ZIMCommandMessage zimCommandMessage = (ZIMCommandMessage) zimMessage;
                
           }    
        }
    }
});
1
Copied!

Send/Receive custom messages

The ZIM SDK supports developers in implementing the sending and receiving of custom message types. Developers can define their own message types using the ZIMCustomMessage object, such as voting, chain, video card, and more. Developers can follow these steps to implement the sending and receiving of custom messages.

Note
  • Only ZIM SDK version 2.8.0 and above supports sending custom type messages, receiving and viewing the content of custom type messages.
  • If the SDK version of the receiving end is between [2.0.0, 2.8.0), the custom message can be received, but the message type will be displayed as unknown and the information content cannot be obtained. To get this message, please upgrade the SDK to version 2.8.0 or above.
  • If the SDK version of the receiving end is version 1.x.x, you cannot receive custom messages or unknown messages.

Send custom messages

The interface used to send custom messages is sendMessage, which is the same as the interface used to send regular messages. Developers can refer to Send & Receive messages - Send messages to learn about this interface Parameter details.

Developers need to define custom type messages through the ZIMCustomMessage object.

Untitled
// Send a custom message to specified users in a one-to-one conversation
String userID = "xxxx";

// Customize the text content of the message
String message = "";

// Specific custom type
int subType = 100; 

// Customize the search field of the message.
String searchedContent = "";

ZIMCustomMessage zimCustomMessage = new ZIMCustomMessage(message,subType);

// Advanced property configuration for sending messages
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set message priority
config.priority = ZIMMessagePriority.LOW;

// Send one-to-one conversation message 
ZIMConversationType type = ZIMConversationType.Peer;


zim.sendMessage(zimCustomMessage, userID, type, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage zimMessage) {
        // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.            
    }

    @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
        // You can use this callback to monitor whether the message is sent successfully.
    }
});
1
Copied!

Receive custom messages

The callback interface for receiving custom messages is the same as the callback interface for receiving regular messages. Please refer to Send & Receive messages - Receive messages for details on the specific interface.

The following is an example code for receiving custom messages in a one-to-one conversation:

Untitled
// User receives custom message in a one-to-one conversation
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromUserID) {
        // Callback when receiving "one-to-one conversation" message
        for (ZIMMessage zimMessage : messageList) {
            if (zimMessage instanceof ZIMCustomMessage) {
                ZIMCustomMessage zimCustomMessage = (ZIMCustomMessage) zimMessage;
                
           }    
        }
    }
});
1
Copied!

Send/Receive multi-item messages

ZIM SDK supports sending multiple types of content in a single message, such as text, images, and more. This type of message is referred to as a "multi-message. You can define this type of message by using the ZIMCustomMessage object.

Note
  • Only ZIM SDK version 2.19.0 and above supports sending multi-item messages, receiving and viewing the content of multi-item messages.
  • If the SDK version of the receiving end is between [2.0.0, 2.19.0), the multi-item message can be received, but the message type will be displayed as unknown and the information content cannot be obtained. To get this message, please upgrade the SDK to version 2.19.0 or above.
  • If the SDK version of the receiving end is version 1.x.x, you cannot receive multi-item messages or unknown messages.

Send multi-item messages

After the user logs in successfully, they can send 1 message containing various types of content (such as text, images, audio, video, files, and custom messages) using the ZIMMultipleMessage object in one-to-one chats, room chats, or group chats via the sendMessage interface.

You can use the onMultipleMediaUploadingProgress callback to receive notifications about the upload progress of rich media files in the multi-item message. This callback provides the following fields:

  • currentFileSize: Total size of the uploaded files, in bytes.
  • totalFileSize: Total size of all rich media files in the multi-item message, in bytes.
  • messageInfoIndex: The index of the currently uploading file in the ZIMMultipleMessage array.
  • currentIndexFileSize: Uploaded size of the currently uploading file, in bytes.
  • totalIndexFileSize: Actual size of the currently uploading file, in bytes.

These fields can be used to calculate the overall upload progress and the progress of the current file being uploaded:

  • Total upload progress = currentFileSize / totalFileSize.
  • Current file upload progress = currentIndexFileSize / totalIndexFileSize.
Untitled
// Send a multi-item message in a one-to-one conversation

String userID = "xxxx";

// The item list of multi-item message can contain a maximum of 20 items.
ArrayList<ZIMMessageLiteInfo> messageInfoList = new ArrayList();

// Text
ZIMTextMessageLiteInfo textMsgInfo= new ZIMTextMessageLiteInfo();
textMsgInfo.message = "Message content";
messageInfoList.add(textMsgInfo);

// Custom message: Only 1 allowed. 
ZIMCustomMessageLiteInfo customMsgInfo= new ZIMCustomMessageLiteInfo();
customMsgInfo.message = "Message content";
customMsgInfo.searchedContent = "Searched";
customMsgInfo.subType = 100;
messageInfoList.add(customMsgInfo);

// Image: Only 10 allowed.
// Online image
ZIMImageMessageLiteInfo imageMsgInfo= new ZIMImageMessageLiteInfo();
imageMsgInfo.fileDownloadUrl = "https://xxxx.jpeg"; // Original Image
imageMsgInfo.thumbnailDownloadUrl = "https://xxxx-thumbnail.jpeg"; // Thumbnail
imageMsgInfo.largeImageDownloadUrl = "https://xxxx-large.jpeg"; // Large Image
messageInfoList.add(imageMsgInfo);

// Local Image
ZIMImageMessageLiteInfo localImageMsgInfo= new ZIMImageMessageLiteInfo();
localImageMsgInfo.fileLocalPath = "/storage/emulated/0/Android/data/packagename/xxx.jpg"; // Absolute path of the image
messageInfoList.add(localImageMsgInfo);

// File: Only 1 allowed. 
ZIMFileMessageLiteInfo localFileMsgInfo= new ZIMFileMessageLiteInfo();
localFileMsgInfo.fileLocalPath = "/storage/emulated/0/Android/data/packagename/xxx.zip"; // Absolute path of the file
messageInfoList.add(localFileMsgInfo);

// Audio: Only 1 allowed. 
ZIMAudioMessageLiteInfo localAudioMsgInfo= new ZIMAudioMessageLiteInfo();
localAudioMsgInfo.fileLocalPath = "/storage/emulated/0/Android/data/packagename/xxx.mp3"; // Absolute path of the audio
localAudioMsgInfo.audioDuration = 100; // Required: Audio duration in seconds.
messageInfoList.add(localAudioMsgInfo);

// Video: Only 1 allowed. 
ZIMVideoMessageLiteInfo localVideoMsgInfo= new ZIMVideoMessageLiteInfo();
localVideoMsgInfo.fileLocalPath = "/storage/emulated/0/Android/data/packagename/xxx.mp4"; // Absolute path of the video
localVideoMsgInfo.videoDuration = 100; // Required: Video duration in seconds.
messageInfoList.add(localVideoMsgInfo);


ZIMMultipleMessage zimMultipleMessage = new ZIMMultipleMessage();
zimMultipleMessage.setMessageInfoList(messageInfoList);

// Advanced configuration for sending messages.
ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Message Priority
config.priority = ZIMMessagePriority.LOW;

ZIMConversationType type = ZIMConversationType.Peer;

zim.sendMessage(zimMultipleMessage, userID, type, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage zimMessage) {
        // Developers can use this callback to monitor whether a message is ready to be sent. Only messages that pass the local basic parameter validation will trigger this callback; otherwise, an error will be returned through the onMessageSent callback.              
    }

    @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
        // Developers can use this callback to monitor whether the message was sent successfully.
    }

    @Override
    public void onMultipleMediaUploadingProgress(
        ZIMMultipleMessage message,
        long currentFileSize,      // Total size of uploaded files in bytes (B). For example, if 20,971,520 Byte has been uploaded, this value will be 20,971,520.
        long totalFileSize,        // Total file size in bytes (B). For example, if the total file size is 104,857,600 Byte, this value will be 104,857,600.
        int messageInfoIndex,      // The index of the currently uploading file in the messageInfoList array when this callback is received.
        long currentIndexFileSize, // The uploaded size of the currently uploading file in bytes (B) when this callback is received.
        long totalIndexFileSize,   // The size of the currently uploading file when this callback is received.
    ) {
        // You can display the upload progress here on the UI.
        // Developers can use this callback to monitor the upload progress of multimedia files.
        // Total file upload progress: currentFileSize / totalFileSize.
        // In the above example, the total file upload progress is: 20,971,520 / 104,857,600 = 20%.
        // When this callback is received, the upload progress of the currently uploading file is: currentIndexFileSize / totalIndexFileSize.
    }
});
1
Copied!

Receive multi-item messages

接收组合消息的回调接口与接收普通消息的回调接口一致,请参考 收发普通消息 - 接收消息 了解具体接口。

The callback interface for receiving multi-item messages is the same as the callback interface for receiving regular messages. Please refer to Send & Receive messages - Receive messages for details on the specific interface.

The following is an example code for receiving multi-item messages in a one-to-one conversation:

Untitled
// // User receives multi-item message in a one-to-one conversation
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onPeerMessageReceived(ZIM zim, ArrayList<ZIMMessage> messageList, ZIMMessageReceivedInfo info, String fromUserID) {
        for (ZIMMessage zimMessage : messageList) {
            if (zimMessage instanceof ZIMMultipleMessage) {
                // This indicates that a multi-item message has been received.
                ZIMMultipleMessage zimMultipleMessage = (ZIMMultipleMessage) zimMessage;
                
           }    
        }
    }
});
1
Copied!

Send/Receive @ messages

An "@" message refers to a message that contains the content of "@ + user". When a user is mentioned with an "@" message, they receive a strong notification.

Note

The "@" message is not a message type itself. A message can be both a text message or another type of message, and it can also be an "@" message.

Send @ messages

When calling sendMessage to send a message, you can use the following methods (can be used simultaneously) to mark a message as an "@" message:

  • mentionedUserIDs: Notifies specific users (including users outside of the conversation) to view the message. The length of the userID list passed in should be up to 50. If you need to increase this limit, please contact the ZEGOCLOUD technical support team.
  • isMentionAll: Notifies all other users within the conversation to view the message.
Note

Only ZIM SDK version 2.14.0 and above supports sending messages with @ information.

Untitled
// The following is a sample code for a user to send an @ message in a single conversation:

// Create a list of users to be mentioned
ArrayList<String> mentionArrayList = new ArrayList<>();

// Add a user (the user does not need to be in the current conversation)
mentionArrayList.add("userId1");
mentionArrayList.add("userId2");

// message can be any type of message
// Call the interface to remind users in the list to view messages
message.setMentionedUserIDs(mentionArrayList);

// Remind all other users in the conversation to view the message
boolean isMentionAll = true;
message.setIsMentionAll(isMentionAll);

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set message priority
config.priority = ZIMMessagePriority.LOW;

// Whether to forcefully push the notification to the alerted user (regardless of whether the other party has enabled Do Not Disturb mode), the default is fasle;
config.isNotifyMentionedUsers = true;

// Take sending a one-to-one conversation message as an example
ZIMConversationType type = ZIMConversationType.Peer;

zim.sendMessage(message, "conv_id", type, config, new ZIMMessageSentFullCallback() {
    @Override
    public void onMessageAttached(ZIMMessage zimMessage) {
        // You can use this callback to monitor whether the message is ready to be sent. This callback will be thrown only if the message passes the local basic parameter verification, otherwise an error will be thrown through the onMessageSent callback.           
    }

  @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
         // Developers can use this callback to monitor whether the message is sent successfully.
    }
}];

1
Copied!

Receive @ messages

The callback interface for receiving @ messages is the same as the callback interface for receiving regular messages. Please refer to Send & Receive messages - Receive messages for details on the specific interface.

After receiving a message, developers can implement corresponding functionalities based on their business logic, such as highlighting, etc.

Note
  • Only ZIM SDK versions 2.14.0 and above support receiving and viewing the content of @ messages.
  • If the SDK version on the receiving end is between [2.0.0, 2.14.0), the received messages and conversations will not contain @ information.
  • If the SDK version on the receiving end is version 1.x.x, @ messages cannot be received.

Receive mentionedInfoList

After users within a conversation are mentioned, developers can passively or actively retrieve mentionedInfoList.

mentionedInfoList contains the corresponding message ID, sender userID, and the type of ZIMMessageMentionedType.Developers can use this information to implement various business logics, such as marking conversations.

Passive retrieval

When a user is mentioned, the onConversationChanged will be received, allowing you to retrieve the latest mentionedInfoListfor the current ZIMConversation.

Untitled
@Override
  public void onConversationChanged(
      ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
      // conversationChangeInfoList 
      // You can get the mentionInfoList in the conversation that received the reminder
  }
1
Copied!

Active retrieval

If you use queryConversationList or queryConversation o actively fetch conversations, you can also retrieve the mentionedInfoList within the conversation. Refer to the following example code:

Untitled
ArrayList<ZIMMessageMentionedInfo> mentionedInfoList = conversation.mentionedInfoList;
1
Copied!

:::

Clearing mentionedInfoList of a conversation

After receiving @ messages, users need to clear the mentionedInfoList of the conversation to stop receiving notifications.

The interface for clearing the mentionedInfoList is the same as clearing the unread message count of a conversation:

Get the list of mentioned users

All users within the conversation can call mentionedUserIDs to obtain the specific list of mentioned users.

Untitled
ArrayList<String> userIds = message.getMentionedUserIDs();
1
Copied!

Confirm whether it is a reminder for all members

All users within the conversation can use the isMentionAll parameter of ZIMMessage to determine whether it is a reminder for all members.

Untitled
boolean isMentionAll = message.isMentionAll();
1
Copied!

Send/Receive broadcast messages

ZIM allows you to send messages to all online users of your app from the server side, and the targeted users will receive the messages through the client side.

Send messages to all users from the server side

Please refer to the server-side API documentation Push message to all user to learn how to send messages to all users from the server side.

Receive broadcast messages sent from the server side

Note
  • Only ZIM SDK versions 2.10.0 and above support receiving and viewing the content of broadcast messages sent from the server side.
  • If the SDK version on the receiving end is between [2.0.0, 2.10.0), broadcast messages sent from the server side cannot be received. If you need to access this message, please upgrade the SDK to version 2.10.0 or above.

Through the onBroadcastMessageReceived callback, you can receive push messages from all members.

Sample code:

Untitled
// User receives broadcast messages 
public void onBroadcastMessageReceived(ZIM zim, ZIMMessage message) {
  super.onBroadcastMessageReceived(zim, message);
    // Receive broadcast messages from all members
}
1
Copied!

Forward message

The ZIM SDK supports forwarding messages in one of the following ways:

  • Combining messages and forwarding the combined message.
  • Forwarding messages one by one.

For more information, see Forward messages.

Receive Tips message

ZIM SDK supports converting user operations within a conversation into Tips messages. When a related operation occurs, ZIM SDK will send a Tips message to the session to notify. For details, please refer to Receive tip messages.

Listen for the message status

On a weak network condition, this may happen: the ZIM SDK doesn't receive the response from the server for some reason (e.g., packet loss), while the message is successfully sent. In this case, the ZIM SDK considers the message sending failed due to the reply timeout, but the message is actually sent successfully, which results in message status confusion. To solve this and Clarify the message status, the SDK 2.6.0 or later now allows you to listen for the onMessageSentStatusChanged callback to receive the changes of the message status. And we now have three different message statuses: Sending, Success, and Failed. You can know whether your message is sent successfully by the status, and implement your event handling logic as needed.

Untitled
//  Listen for the message status 
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onMessageSentStatusChanged(
        ZIM zim, ArrayList<ZIMMessageSentStatusChangeInfo> messageSentStatusChangeInfoList) {
            // You can listen for the callback on the changes of message status here.
}
});
1
Copied!

Previous

Manage group members

Next

Get message history