logo
On this page

Send and receive messages


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

Solution

The following shows the access solution that ZEGOCLOUD'S In-app Chat (the ZIM SDK) provides.

/Pics/InappChat/im_solution_en.png

In this solution, you will need to implement the following business logic based on your actual business requirements:

  • The logic for managing the users on the client, and the logic for distributing user ID for users to log in.
  • The logic for generating the Token for SDK to authenticate the user. We recommend you implement the logic for generating tokens on your app server for data security.

Prerequisites

Before you begin, make sure:

  • Go to ZEGOCLOUD Admin Console, and do the following:

    • Create a project, get the AppID and ServerSecret.
    • Activate the In-app Chat service (as shown in the following figure). /Pics/InappChat/ActivateZIMinConsole2.png
  • Get the Token that SDK required for login authentication. For details, see Authentication.

Integrate the SDK

Optional: Create a new project

Skip to this step if a project already exists.

Import the SDK

  1. Execute the npm i zego-zim-web command to install the dependencies.

    Note

    If the error permission denied occurs when executing the npm command on macOS or Linux, add a sudo before the npm command and try again.

  2. Import the SDK.

    Untitled
    import { ZIM } from 'zego-zim-web';
    
    1
    Copied!

    or

    Untitled
    const ZIM = require('zego-zim-web').ZIM;
    
    1
    Copied!

Implementation steps

Get the sample code

To download and run the sample code, see Sample app.

Import the SDK file

Refer to the Method 2: Integrate the SDK with NPM to import the SDK package file.

Create a ZIM SDK instance

Creating a ZIM instance is the very first step, an instance corresponds to a user logging in to the system as a client.

So, let's suppose we have two clients now, client A and client B. To send and receive messages to each other, both of them will need to call the create method with the AppID in the previous Prerequisites steps to create a ZIM SDK instance of their own:

Untitled
var appID = xxxx; // Note: the appID is a set of numbers, not a String. 
// The [create] method creates a ZIM instance only on the first call. Any subsequent calls return null.
ZIM.create({ appID });
// Get the instance via [getInstance] to avoid hot updates that cause you to use the [create] method multiple times to create a singleton and return null.
var zim = ZIM.getInstance();
1
Copied!

Set event callbacks

Before a client user's login, you will need to call the on method to customize the event callbacks, such as you can receive callback notifications when SDK errors occur or receiving message related callback notifications.

Untitled
// Set up and listen for the callback for receiving error codes. 
zim.on('error', function (zim, errorInfo) {
    console.log('error', errorInfo.code, errorInfo.message);
});

// Set up and listen for the callback for connection status changes.
zim.on('connectionStateChanged', function (zim, { state, event, extendedData }) {
    console.log('connectionStateChanged', state, event, extendedData);
    // When SDK logout occurred due to a long-time network disconnection, you will need to log in again. 
    if (state == 0 && event == 3) {
        zim.login(userInfo, token)
    }
});

// Set up and listen for the callback for receiving one-to-one messages. 
zim.on('peerMessageReceived', function (zim, { messageList, fromConversationID }) {
    console.log('peerMessageReceived', messageList, fromConversationID);
});

// Set up and listen for the callback for token expires.
zim.on('tokenWillExpire', function (zim, { second }) {
    console.log('tokenWillExpire', second);
    // You can call the renewToken method to renew the token. 
    // To generate a new Token, refer to the Prerequisites.
    zim.renewToken(token)
        .then(function({ token }){
            // Renewed successfully.
        })
        .catch(function(err){
            // Renew failed.
        })
});
1
Copied!

For a detailed introduction to the interfaces, please refer to connectionStateChanged, peerMessageReceived, tokenWillExpire.

Log in to the ZIM SDK

For client A and client B to send, receive messages, and renew the token after creating the ZIM SDK instance, they will need to log in to the ZIM SDK.

To log in, Clients A and B both need to do the following:

  1. Call the ZIMUserInfo method to create a user object.
  2. Then, call the login method with their own user information and the Token they get in the previous Prerequisites steps.
Warning
  • You can custom the userID and userName, and we recommend you set these two to a meaningful value and associate them with the account system of your application.
  • If the token has expired, you will need to call the renewToken method in the tokenWillExpire method to renew the token before you try again.
Untitled
// To get the token for login, refer to the [Guides - Authentication] document. 
// userID must be within 32 bytes, and can only contain letters, numbers, and the following special characters: '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'.
// userName must be within 256 bytes, no special characters limited.
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var token = '';

zim.login(userInfo, token)
    .then(function () {
        // Login successful.
    })
    .catch(function (err) {
        // Login failed.
    });
1
Copied!

Send messages

Client A can send messages to client B after logging in successfully.

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.

To send one-to-one messages, for example, if client A wants to send a message to client B, then client A needs to call the sendMessage method with client B's userID, message content, and other info. And client A can be notified whether the message is delivered successfully through the callback ZIMMessageSentResult.

  • onMessageAttached callback: The callback on the message not sent yet. Before the message is sent, you can get a temporary ZIMMessage message for you to implement your business logic as needed. For example, you can get the ID of the message before sending it. Or when sending a message with large content, such as a video, you can get the localMessageID of the message before the message is uploaded to implement a Loading UI effect.
Untitled
//  Send one-to-one text messages. 

var toConversationID = ''; // Peer user's ID.
var conversationType = 0; // Message type; One-to-one chat: 0, in-room chat: 1, group chat:2 
var config = { 
    priority: 1, // Set priority for the message. 1: Low (by default). 2: Medium. 3: High.
};

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

var messageTextObj = { type: 1, message: 'Message text', extendedData: 'Message extended info(optional)' };

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

Receive messages

After client B logs in, he will receive client A's message through the callback on which is already set in the peerMessageReceived method.

Untitled
// Set up and listen for the callback for receiving the one-to-one messages. 
zim.on('peerMessageReceived', function (zim, { messageList, fromConversationID }) {
    console.log('peerMessageReceived', messageList, fromConversationID);
});
1
Copied!

Log out

For a client to log out, call the logout method.

Untitled
zim.logout();
1
Copied!

Destroy the ZIM SDK instance

To destroy the ZIM SDK instance, call the destroy method.

Untitled
zim.destroy();
1
Copied!

Previous

Sample code

Next

SDK downloads