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 on 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 on to listen for the callback on the result of message sending peerMessageReceived.
  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 peerMessageReceived 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

var toConversationID = ''; // The userID of the message receiver
var conversationType = 0; // Applicable value: 0 (one-to-one), 1 (room), 2 (group).
var config = { 
    // Set the message priority.
    // The applicable value is 1 (low, default), 2 (middle), 3 (high).
    priority: 1,
};

var notification = {
    onMessageAttached: function(message) {
        // 
    }
}

var messageTextObj = {
    type: 1,
    message: 'xxxx'
};

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // Sent successfully
    })
    .catch(function (err) {
        // failed to send
    });
1
Copied!

Receive messages

Note
Untitled
// Callback for receiving the one-to-one message.
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});

// Callback for receiving the group message.
zim.on('groupMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});

// Callback for receiving the in-room message.
zim.on('roomMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
});
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.

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
function onMediaUploadingProgress(message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number);
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): peerMessageReceived, roomMessageReceived, groupMessageReceived, 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.
Untitled
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    const config = {messageInfoIndex: 0}
    messageList.forEach((msg) => {
        if (msg.type == 11) {
            zim.downloadMediaFile(msg, 1, config (_msg, currentFileSize, totalFileSize) => {});
        }
    });
});
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
function ZIMMediaDownloadingProgress(message: ZIMMessage, currentFileSize: number, totalFileSize: number);
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

Untitled
// Send signaling messages to a specified user.
var toConversationID = ''; // The recipient's user ID.
var conversationType = 0; // 0: one-to-one, 1: room, 2: group
var config = { 
    priority: 1, // 1: low (default), 2: middle, 3: high
};

var notification = {
    onMessageAttached: function(message) {
        // 
    }
}

// Here, a JSON string is used as an example, and the string needs to be converted to a Uint8Array.  
// When `peerMessageReceived` receives a message with type 2, the Uint8Array needs to be converted back to a JSON string.  
var jsonText = JSON.stringify({ id: '111', name: '张三' });
var uint8Array = new Uint8Array(Array.from(unescape(encodeURIComponent(jsonText))).map((val) => val.charCodeAt(0)));

var messageCommandObj = { type: 2, message: uint8Array };

zim.sendMessage(messageCommandObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // Sent successfully
    })
    .catch(function (err) {
        // Failed to send
    });
1
Copied!

Receive signaling messages

Untitled
// Receive signaling messages.
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
    messageList.forEach(function (msg) {
        // Here, take the JSON string as an example, which needs to be converted to Uint8Array.
        if (msg.type == 2) {
            var uint8Array = msg.message;
            var jsonText = decodeURIComponent(escape(String.fromCharCode(...Array.from(uint8Array))));
            var jsonObj = JSON.parse(jsonText);
            console.log('peerMessageReceived', jsonObj);
        }
    })
});
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 a specified user

// Pass in the userID of the message receiver
var toConversationID = "xxxx";
var conversationType = 0; // 0: One-to-one; 1: Room,2: Group
// Advanced settings
var config = { 
    priority: 1, // Message priority: 1: Low (default); 2: Medium; 3: High.
};

var notification = {
    onMessageAttached: function(message) {
        // 
    }
}

var zimCustomMessage = {
    type: 200,
    message: 'xxxx', // Text of custom message
    subType: 100, // Specific custom message type
    searchedContent: 'xxxx' 
};

zim.sendMessage(zimCustomMessage, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // Sent successfully
    })
    .catch(function (err) {
        // Failed to send
    });
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
// Receive a custom messages in a one-to-one conversation
zim.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, info, fromConversationID);
    messageList.forEach(function (msg) {
        // When receiving a custom message
        if (msg.type == 200) {
        }
    })
});
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 multipleMediaUploadingProgress 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
// The method to select a local file
var file = ''; // Absolute path of the file to be uploaded
1
Copied!
Untitled
// Send a multi-item message in a one-to-one conversation

// Pass in the userID of the message receiver
var toConversationID = "xxxx";
// Advanced configuration for sending messages.
var conversationType = 0; // 0: One-to-one; 1: Room; 2: Group
var config = { 
    priority: 1, // Message Priority, 1: low (default), 2: medium, 3: high
};

var notification = {
    onMessageAttached: function(message) {
        // 
    },
    onMultipleMediaUploadingProgress: function(
        message,
        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.
        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.
        messageInfoIndex,     // The index of the currently uploading file in the messageInfoList array when this callback is received.
        currentIndexFileSize, // The uploaded size of the currently uploading file in bytes (B) when this callback is received.
        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.
    }
};

var zimMultipleMessage = {
    type: 10,
    // The item list of multi-item message can contain a maximum of 20 items.
    messageInfoList: [
        // Text
        {
            type: 1,
            message: 'xxxx',
        },
        // Custom message
        {
            type: 200,
            message: 'xxxx',
            subType: 100,
            searchedContent: 'xxxx'
        },
        // Image: Only 10 allowed.
        // Online image
        {
            type: 11,
            fileDownloadUrl: 'https://xxxx.jpeg', // Original Image
            thumbnailDownloadUrl: 'https://xxxx-thumbnail.jpeg', // Thumbnail
            largeImageDownloadUrl: 'https://xxxx-large.jpeg', // Large Image
        },
        // Local Image
        {
            type: 11,
            fileLocalPath: file, // File to be uploaded
        },
        // File: Only 1 allowed. 
        {
            type: 12,
            fileLocalPath: file, // File to be uploaded
        },
        // Audio: Only 1 allowed. 
        {
            type: 13,
            fileLocalPath: file, // File to be uploaded
            audioDuration: 100, // Required: Audio duration in seconds.
        },
        // Video: Only 1 allowed. 
        {
            type: 14,
            fileLocalPath: file, // File to be uploaded
            videoDuration: 100, // Required: Video duration in seconds.
        }
    ]
};

zim.sendMessage(zimMultipleMessage, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // Sent successfully
    })
    .catch(function (err) {
        // Failed to send
    });
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.on('peerMessageReceived', function (zim, { messageList, info, fromConversationID }) {
    console.log(messageList, fromConversationID);
    messageList.forEach(function (msg) {
        // This indicates that a multi-item message has been received.
        if (msg.type == 10) {
            msg.messageInfoList.forEach(function (info) {
                // Display UI based on the message type.
                console.log('The item type:' + info.type);
            }
        }
    })
});
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
// Below is an example code for a user sending an @ message (text message) in a one-to-one conversation: 
var toConversationID = ''; // the userID of message receiver
var conversationType = 0; // Conversation type, with values: One-to-one: 0, Room: 1, Group: 2.
var config = { 
    priority: 1, // Set message priority, with values: Low: 1 (default), Medium: 2, High: 3.
};

var notification = {
    onMessageAttached: function(message) {
        // 
    }
}

var messageTextObj = {
    type: 1,
    message: 'xxxx',
    isMentionAll: true, // Remind all other users in the conversation to check the message.
    mentionedUserIDs: ["userId1", "userId2"], // Remind users in the list to check the message.
};

zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
    .then(function ({ message }) {
        // Sent successfully
    })
    .catch(function (err) {
        // Failed to send
    });


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 conversationChanged will be received, allowing you to retrieve the latest mentionedInfoListfor the current ZIMConversation.

Untitled
zim.on('conversationChanged', function (zim, { info }) {
    console.log(info.mentionInfoList);
});
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
var mentionedInfoList = conversaion.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
var userIds = message.mentionedUserIDs;
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
var 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 broadcastMessageReceived callback, you can receive push messages from all members.

Sample code:

Untitled
 // User receives broadcast messages
zim.on('broadcastMessageReceived', function (zim, { message }) {
    console.log(message);
});
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 messageSentStatusChanged 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.on('messageSentStatusChanged', function (zim, { infos }) {
    infos.forEach( function (info) {
        console.warn(info.message, info.status);
    });  
});
1
Copied!

Previous

Manage group members

Next

Get message history