Registry / communication / agora-rtm-sdk

agora-rtm-sdk

JSON →
library2.2.4jsnpmunverified

The Agora Real-time Messaging (RTM) SDK for JavaScript, currently stable at version 2.2.4, provides robust real-time interaction capabilities for client applications. This SDK enables developers to integrate feature-rich, scalable, and proven real-time engagement solutions, moving beyond basic messaging to support complex scenarios like conference control, interactive games, metaverse applications, online education, e-commerce, and smart devices. Version 2.x represents a significant iteration, offering enhanced functions, improved performance, and a better user experience compared to its predecessors. While an explicit release cadence isn't stated, the continuous iteration to version 2.x and ongoing updates (such as v2.2.8 released Feb 2026) suggest active development and maintenance. Key differentiators include its proven reliability with over 3000 customers, wide applicability across diverse use cases, and strong focus on scalable real-time messaging, often complementing Agora's RTC (Real-time Communication) offerings for voice and video.

communicationhttp-networking
npm install agora-rtm-sdk
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AgoraRTM
import AgoraRTM from 'agora-rtm-sdk';
const AgoraRTM = require('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
import { ConnectionState } from 'agora-rtm-sdk';
import AgoraRTM, { 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()`.

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();
Debug
Known issues
breakingMigration 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.
affects: >=2.0.0
gotchaApplications 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.
affects: >=1.0.0
gotchaAgora 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.
affects: >=1.0.0
gotchaWhen 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.
affects: >=2.2.0
Errors
Common errors & fixes
RTM:ERROR Error Code -10002, server Code 26 - Login RTM service was rejected due to server error. apCode is 26, unexpected code.
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
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
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)`.
Upgrade
Version history
2.2.4latest on PyPI
Audit
Dependencies
agora-rtc-sdk-ngoptionalPeer dependency, commonly used for integrating real-time voice and video alongside RTM messaging functionality for a complete communication solution.
Agent activity
94 hits · last 30 days
node
10
petalbot
5
claudebot
4
ahrefsbot
3
bytedance
3
Amazon
2
amazonbot
1
Resources