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

Send and receive messages


This document describes how to use the ZIM SDK (In-app Chat) to send and receive messages.

Prerequisites

Before you begin, make sure:

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

    • Create a project, get the AppID and AppSign.
    • Activate the In-app Chat service (as shown in the following figure). /Pics/InappChat/ActivateZIMinConsole2.png
  • Platform-specific requirements:

    • React Native 0.60.0 or later
    • A real iOS device that is running on iOS 11.0 or later and supports audio and video.
    • An Android device or Simulator that is running on Android 4.0.3 or later and supports audio and video. We recommend you use a real device (enable the "USB Debugging" option).
    • Your device is connected to the internet.
    • Configure Visual Studio Code, search for the "React Native Tools" extension, and install it.

Integrate the SDK

Optional: Create a new project

Skip to this step if a project already exists.

Import the SDK

The following shows how to integrate the SDK using NPM:

  1. Execute the npm i zego-zim-react-native or yarn add zego-zim-react-nativecommand to install the dependencies.

    Note

    We recommend you use the NPM package that supports the TypeScript language.

  2. Import the SDK.

    Untitled
    import ZIM from 'zego-zim-react-native';
    
    1
    Copied!
  3. Go to the iOS root directory, run the pod install command to install the dependencies.

After completing the above steps, you can use the zego-zim-react-native SDK in your project using JavaScript or TypeScript (recommended).

Implementation steps

Get the sample code

Get the sample code from Sample app.

Import the SDK file

Refer to the Integrate the SDK using 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 into 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
// Since In-app Chat 2.3.0, the SDK uses the AppSign authentication mode by default. To change the authentication mode:
// 1. For SDK 2.3.3 or later, you can change the authentication mode by yourself.  2. For SDK 2.3.0 or later, if you want to change your authentication mode back to using the Token, contact Technical Support.

// Use a static synchronized method to create a ZIM SDK object and pass the AppID and AppSign. 
// The create method creates a ZIM instance only the first time it is called. Any subsequent use will return null. 
ZIM.create({ appID: 0, appSign: '' });
// Please get a single instance via the getInstance method to avoid hot updates that return null multiple times using the create method.
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 receive 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);
});

// Set up and listen for the callback for receiving one-to-one messages. 
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', messageList, fromConversationID);
});
// Register a callback to listen for "Token is about to expire"
zim.on('tokenWillExpire', function (zim, { second }) {
console.log('tokenWillExpire', second);
// You can call the renewToken interface here to update the token
// For new token generation, please refer to the above
zim.renewToken(token)
.then(function({ token }){
// Update successful
})
.catch(function(err){
// Update failed
})
});
1
Copied!

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 ZIMLoginConfig method to create a user object.
  2. Then, call the [login](@ login__2) 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 the userID to a meaningful value and associate them with the account system of your application.

  • For SDK 2.3.0 or later: The SDK uses the AppSign authentication mode by default. You only need to pass the [ZIMUserInfo`](@-ZIMUserInfo) when logging in.

  • If you use the Token-based authentication mode, please refer to the [Authentication](./Guides/Users/Authentication.mdx) to get the Token first, and pass it when logging in.

Untitled
// userID must be within 32 characters, and can only contain letters, numbers, and the following special characters: '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'.
// userName A string of up to 256 bytes, with no restrictions on special characters.
var userInfo = { userID: 'xxxx', userName: 'xxxx' };
var userID = 'xxxx';
var config = {
   userName: 'xxxx',
     token: '',
 }



// When logging in:
// If you use the Token-based authentication, pass the Token you get by referring to the [Guides - Authentication] document.
// If you use the AppSign authentication mode (the default auth mode by SDK 2.3.0), you need to leave the Token field empty. 

zim.login(userID, config)
    .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
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 and in order and can be stored as historical messages, 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.

API: sendMessage

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 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)The on-screen comment in a chat room. An on-screen comment cannot exceed 5 KB in size, and there is no limit on the number of comments that can be sent per second per client.

On-screen comments 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

ZIMImageMessage(11)The image message. Mainstream image formats, such as JPG, PNG, BMP, TIFF, GIF, and WebP, are supported. An image message cannot exceed 10 MB in size, and up to 10 image messages can be sent per second per client.

Image messages are reliable and in order and can be stored as historical messages (for 14 days by default), usually applicable to one-to-one chats, chat rooms, and group chats.

API: sendMediaMessage

ZIMFileMessage(12)The 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)The 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)

The video message. 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.

The width and height of the first frame of a video can be obtained after successful message sending only if the video is H.264- or H.265-encoded.

ZIMCombineMessage(100)Merge messages, there is no limit on message size, and the sending frequency of a single client is limited to 10 times/second.

Text messages are reliable and in order and can be stored as historical messages, applicable to real-time chat scenarios such as one-to-one chats, room, group chats, etc.

API: sendMessage

ZIMCustomMessage(200)The custom message. You can customize the message type and parse the message without using the ZIM SDK.

Custom messages are usually applicable to votes, solitaire, and video cards.

API: sendMessage

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 message type (conversationType).

  • ZIMMessageSentResult: Callback for the results that whether the message is sent successfully.

  • 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
// The following shows to send a one-to-one message, set the ZIMConversationType to Peer. 
var toUserID = 'xxxx1';
var config = { 
    priority: 1 // Set priority for the message. 1: Low (by default). 2: Medium. 3: High.
};
var type = 0; // Session type. Values are: 0: One-on-one chat.  1: Chat room  2: Group chat.
var notification = {
    onMessageAttached: function(message) {
        // todo: Loading
    }
};

// Send one-to-one text messages. 
var messageTextObj = { type: 1, message: 'Text message content' };
zim.sendMessage(messageTextObj, toUserID, type, config, notification)
    .then(function ({ message }) {
        // Message sent successfully.
    })
    .catch(function (err) {
        // Failed to send the 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 receivePeerMessage method.

Untitled
// Set up and listen for the callback for receiving the one-to-one messages.
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
    console.log('receivePeerMessage', 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