Agora Real-time Messaging (RTM) SDK for JavaScript

Common errors

• RTM:ERROR Error Code -10002, server Code 26 - Login RTM service was rejected due to server error. apCode is 26, unexpected code.

  cause The Agora RTM service is likely not enabled for your project, or a data center has not been selected in the Agora Console for Signaling V2.
  fix Log into your Agora Console, navigate to your project, and ensure that the 'Signaling' feature is enabled and a data center is selected under 'All features > Signaling > Basic information'.

• RTM:ERROR Error Code 5: login failed with args / Login failed: Authentication failed / RtmUnauthenticatedError

  cause Incorrect or expired token, invalid App ID, or mismatched UID between the token generation and client login.
  fix Ensure the App ID, User ID (UID), and token (if used) are correct and match what was used for token generation. For production, tokens should be generated server-side. Check server time synchronization if tokens are time-sensitive. If using temporary tokens, ensure the App ID is enabled for debug mode.

• TypeError: AgoraRTM.createInstance is not a function

  cause This usually indicates an incorrect import statement, especially when mixing CommonJS `require` with ESM `import` in a context that expects a different module resolution, or attempting to call `createInstance` directly on the default import without proper destructuring if it's a named export (though `AgoraRTM` is a default export with `createInstance` as a static method/factory).
  fix For ESM, use `import AgoraRTM from 'agora-rtm-sdk';`. For CommonJS, use `const AgoraRTM = require('agora-rtm-sdk');`. Ensure you're calling `createInstance` as a method of the imported `AgoraRTM` object, e.g., `AgoraRTM.createInstance(APP_ID)`.

Warnings

• breaking Migration from Agora RTM SDK 1.x to 2.x involves significant API changes. Key differences include package names (`agora-rtm` vs `rtm-sdk`), initialization parameters, and how channel message event notifications are handled. In 1.x, events were bound to specific channel instances; in 2.x, they are bound to the client instance globally. Ensure all method calls and event listeners are updated according to the 2.x API documentation.
  Fix: Consult the official Agora Signaling 2.x migration guide for a comprehensive list of changes and updated API usage. Refactor initialization, event handling, and channel interactions.
• gotcha Applications built with different `App ID`s do not communicate with each other. To ensure messaging between your applications, you must use the exact same `App ID` during SDK initialization across all clients.
  Fix: Verify that all instances of your application use the identical `App ID` obtained from the Agora Console. For debugging, ensure the App ID is correctly configured and the Signaling feature is enabled for your project in the Agora Console, with a data center selected.
• gotcha Agora RTM SDK has specific browser compatibility requirements. Using unsupported or outdated browser versions may lead to unexpected behavior or complete failure of the SDK functionality. For example, Chrome requires version 90.0 or higher, and Firefox 85.0 or higher.
  Fix: Refer to the 'Requirements' section in the official Agora RTM SDK documentation for a comprehensive list of supported browsers and their minimum versions. Ensure your target environment meets these prerequisites.
• gotcha When integrating `agora-rtm-sdk` (version 2.2.0 or later) with `agora-rtc-sdk-ng` (version 4.3.0 or later), there can be conflicts due to both SDKs including the `libaosl.so` library. This is particularly relevant for Android development.
  Fix: If manually integrating via CDN, delete older versions of `libaosl.so`. If using dependency management, ensure the newer version of `libaosl.so` is included and handle potential conflicts according to Agora's guide on co-integrating Signaling and Video/Voice SDKs. For Android Maven, note the package name change for 2.2.8.

Install

• npm install agora-rtm-sdk npm
• yarn add agora-rtm-sdk yarn
• pnpm add agora-rtm-sdk pnpm

Imports

• AgoraRTM
  wrong:

  const AgoraRTM = require('agora-rtm-sdk');

  correct:

  import AgoraRTM from 'agora-rtm-sdk';

  AgoraRTM is the default export for the SDK client. While `require` might work in some transpiled environments, native ESM `import` is the recommended and modern approach. For TypeScript, ensure `allowSyntheticDefaultImports: true` in `tsconfig.json` if encountering issues with default imports.
• ConnectionState
  wrong:

  import AgoraRTM, { ConnectionState } from 'agora-rtm-sdk';

  correct:

  import { ConnectionState } from 'agora-rtm-sdk';

  Enums like `ConnectionState` are typically named exports. Do not attempt to import them as part of the default `AgoraRTM` object or as a default export themselves.
• RTMClient

  import type { RTMClient } from 'agora-rtm-sdk';

  When using TypeScript, it is best practice to import types using `import type` to ensure they are stripped during compilation and do not introduce runtime overhead or conflicts. `RTMClient` is the interface for the client instance returned by `AgoraRTM.createInstance()`.

Quickstart

This quickstart initializes the Agora RTM client, logs in with a user ID and optional token, joins a specified channel, and sends a text message to that channel. It also sets up event listeners for connection state changes and incoming peer/channel messages.

import AgoraRTM from 'agora-rtm-sdk';

const APP_ID = process.env.AGORA_APP_ID ?? '';
const UID = process.env.AGORA_UID ?? String(Math.floor(Math.random() * 100000));
const CHANNEL_NAME = 'my_agora_channel';

async function startRTMClient() {
  if (!APP_ID) {
    console.error('AGORA_APP_ID is not set. Please set it as an environment variable or replace the placeholder.');
    return;
  }

  const client = AgoraRTM.createInstance(APP_ID);
  console.log('RTM Client created.');

  client.on('ConnectionStateChange', (newState, reason) => {
    console.log(`Connection state changed to ${newState}, reason: ${reason}`);
    if (newState === 'CONNECTED') {
      console.log('Successfully connected to Agora RTM.');
    }
  });

  client.on('MessageFromPeer', ({ text }, peerId) => {
    console.log(`Peer message from ${peerId}: ${text}`);
  });

  try {
    await client.login({ uid: UID, token: undefined }); // Use undefined for temporary token in debug mode
    console.log(`Logged in as ${UID}.`);

    const channel = client.createChannel(CHANNEL_NAME);
    console.log(`Channel '${CHANNEL_NAME}' created.`);

    channel.on('ChannelMessage', ({ text }, senderId) => {
      console.log(`Channel message from ${senderId}: ${text}`);
    });

    await channel.join();
    console.log(`Joined channel '${CHANNEL_NAME}'.`);

    await channel.sendMessage({ text: 'Hello, Agora RTM Channel!' });
    console.log('Message sent to channel.');

  } catch (err) {
    console.error('Agora RTM error:', err);
  }
}

startRTMClient();