Real-time Message SDK for JavaScript

Table of contents

1. Introduction

2. Requirements

3. Getting started

4. Sending your first message

5. Additional information

Important Notice

RTM javaScript SDK has been iterated to version 2.X, which will provide richer functions, better performance and better user experience. We hope that both new and returning users will be able to migrate to the new version to take advantage of its amazing new features.

Introduction

The RTM SDK for javaScript allows you to easily add real-time interactions to client applications. RTM provides feature-rich, scalable, and proven real-time engagement solutions trusted by companies like Glance, Poshmark, Litmatch, 米哈游(miHoyo), and 小天才(Imoo), etc.

RTM has been widely used by 3000+ customers in dozens of application scenarios such as conference control, interactive games, metaverse, online education, e-commerce retail, smart devices, etc.

How it works

The RTM SDK provides complete functionality to provide a rich real-time interactive experience by instantiating an RTM instance, logging in, subscribing to a channel, implementing event listeners to receive messages and other events, and the ability to send messages. Once this basic function is in place, congratulations, you can now interact with anyone in the world online in real time!

Once you've done this, take a look at all the other features RTM supports and add the ones that work best for your users.

Documentation

Find out more about RTM SDK for JavaScript in the documentation. If you have any comments, questions or feature requests, let us know by sending email to [email protected].

Requirements

This section shows you the prerequisites you need to check for using RTM SDK for JavaScript.

Supported browsers

| Browser | Supported versions | | :--------------------: | --------------------------- | | Chrome macOS | 90.0 or higher | | Chrome Linux | 93.0 or higher | | Chrome Windows | 90.0 or higher | | Firefox macOS | 85.0 or higher | | Firefox Windows | 85.0 (x64) or higher | | Microsoft Edge macOS | 114.0.1823.41 or higher | | Microsoft Edge Windows | 113.0.1774.57 or higher | | Safari macOS | 15.6.1 or higher |

Getting started

Step 1: Create a Agora Project from your console

Before installing RTM SDK, you need to create an Agora project on the console. You will need the App ID of your RTM application when initializing the RTM SDK. In order to quickly experience the features, please select debug mode in the authentication mechanism column when creating the project.

Note: Your application built with different App ID do not communicate with each other. To send and receive messages between different apps, you need to make sure you use the same App ID.

Step 2 : Install the RTM SDK

You can obtain the latest RTM JavaScript SDK through any of the following methods.

npm

npm install agora-rtm-sdk

Note: To use npm to install the RTM SDK, Node.js must be first installed on your system.

CDN

Click here download the latest version of the JavaScript SDK and add the following code to your project to reference it:

<script src="your_path_to_sdk/agora-rtm.x.y.z.min.js"></script>

Replace x.y.z with the specific SDK version number, such as 2.1.4

Step 3: Import the RTM SDK

import AgoraRTM from 'agora-rtm-sdk';

If you are using TypeScript and have trouble importing Sendbird, please check your tsconfig.json file and change the value of allowSyntheticDefaultImports to true in compilerOptions.

Sending your first message

Now that the RTM SDK has been imported, we're ready to start sending a message.

Step 4: Initialize the RTM client instance

In order to use the features of the RTM SDK, you should initiate the RTM instance at first:

import AgoraRTM from 'agora-rtm-sdk';

const { RTM } = AgoraRTM;
// Fill in the App ID of your project.
const appId = "your_appId";
// Fill in your user ID.
const userId = "your_userId";
const msChannelName = "Chat_room";

try {
  const rtm = new RTM(appId, userId);
} catch (status) {
  console.log("Error");
  console.log(status);
}

You need to replace "your_appId" and "your_userId" in the code with your project's App ID and your user ID.

Step 5: Add event listener

The event listener helps you implement the processing logic after the messages and events received in the channel. Add the following code to your program to display the received messages or event notifications:

// Paste the following code snippet below "Add the event listener" comment
// Message event handler.
rtm.addEventListener("message", event => {
  showMessage(event.publisher, event.message);
});
// Presence event handler.
rtm.addEventListener("presence", event => {
  if (event.eventType === "SNAPSHOT") {
    showMessage("INFO", "I Join");
  }
  else {
    showMessage("INFO", event.publisher + " is " + event.type);
  }
});
// Connection state changed event handler.
rtm.addEventListener("status", event => {
  // The current connection state.
  const currentState = event.state;
  // The reason why the connection state changes.
  const changeReason = event.reason;
  showMessage("INFO", JSON.stringify(event));
});

Step 6: Login to RTM server

Once the SDK is initialized, your client app can then login to the RTM server. If you attempt to call a RTM SDK method without login, an RTM_ERROR_NOT_LOGIN (-10002) error would return.

// Paste the following code snippet below "Log in the RTM server." comment
try {
  const result = await rtm.login({ token: 'your-token'});
  console.log(result);
} catch (status) {
  console.log(status);
}

Step 7：Send and receive messages

After calling the publish method to send a message to the Message Channel, RTM will distribute the message to all subscribers of the channel. The following code demonstrates how to send a string type message. Add this code snippet to the program:

You need to string serialize the message payload before calling the publish method to send the message.

try {
  const result = await rtm.publish(msChannelName, message);
  console.log(result);
} catch (status) {
  console.log(status);
}

Call the subscribe method to subscribe to this channel to receive messages in this channel. Add the following code to your program:

try {
  const result = await rtm.subscribe(msChannelName);
  console.log(result);
} catch (status) {
  console.log(status);
}

Additional information

Now, you have learned how to use the RTM JavaScript SDK to send and receive messages. Next, you can learn how to use more functions through the SDK's API reference.

If you have any comments, questions or feature requests, let us know by sending email to [email protected].