{"id":10487,"library":"agora-rtm-sdk","title":"Agora Real-time Messaging (RTM) SDK for JavaScript","description":"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.","status":"active","version":"2.2.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","agora","rtm","real-time-messaging","sdk","signaling","stream","messaging","typescript"],"install":[{"cmd":"npm install agora-rtm-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add agora-rtm-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add agora-rtm-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, commonly used for integrating real-time voice and video alongside RTM messaging functionality for a complete communication solution.","package":"agora-rtc-sdk-ng","optional":true}],"imports":[{"note":"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.","wrong":"const AgoraRTM = require('agora-rtm-sdk');","symbol":"AgoraRTM","correct":"import AgoraRTM from 'agora-rtm-sdk';"},{"note":"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.","wrong":"import AgoraRTM, { ConnectionState } from 'agora-rtm-sdk';","symbol":"ConnectionState","correct":"import { ConnectionState } from 'agora-rtm-sdk';"},{"note":"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()`.","symbol":"RTMClient","correct":"import type { RTMClient } from 'agora-rtm-sdk';"}],"quickstart":{"code":"import AgoraRTM from 'agora-rtm-sdk';\n\nconst APP_ID = process.env.AGORA_APP_ID ?? '';\nconst UID = process.env.AGORA_UID ?? String(Math.floor(Math.random() * 100000));\nconst CHANNEL_NAME = 'my_agora_channel';\n\nasync function startRTMClient() {\n  if (!APP_ID) {\n    console.error('AGORA_APP_ID is not set. Please set it as an environment variable or replace the placeholder.');\n    return;\n  }\n\n  const client = AgoraRTM.createInstance(APP_ID);\n  console.log('RTM Client created.');\n\n  client.on('ConnectionStateChange', (newState, reason) => {\n    console.log(`Connection state changed to ${newState}, reason: ${reason}`);\n    if (newState === 'CONNECTED') {\n      console.log('Successfully connected to Agora RTM.');\n    }\n  });\n\n  client.on('MessageFromPeer', ({ text }, peerId) => {\n    console.log(`Peer message from ${peerId}: ${text}`);\n  });\n\n  try {\n    await client.login({ uid: UID, token: undefined }); // Use undefined for temporary token in debug mode\n    console.log(`Logged in as ${UID}.`);\n\n    const channel = client.createChannel(CHANNEL_NAME);\n    console.log(`Channel '${CHANNEL_NAME}' created.`);\n\n    channel.on('ChannelMessage', ({ text }, senderId) => {\n      console.log(`Channel message from ${senderId}: ${text}`);\n    });\n\n    await channel.join();\n    console.log(`Joined channel '${CHANNEL_NAME}'.`);\n\n    await channel.sendMessage({ text: 'Hello, Agora RTM Channel!' });\n    console.log('Message sent to channel.');\n\n  } catch (err) {\n    console.error('Agora RTM error:', err);\n  }\n}\n\nstartRTMClient();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'.","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.","error":"RTM:ERROR Error Code -10002, server Code 26 - Login RTM service was rejected due to server error. apCode is 26, unexpected code."},{"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.","cause":"Incorrect or expired token, invalid App ID, or mismatched UID between the token generation and client login.","error":"RTM:ERROR Error Code 5: login failed with args / Login failed: Authentication failed / RtmUnauthenticatedError"},{"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)`.","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).","error":"TypeError: AgoraRTM.createInstance is not a function"}],"ecosystem":"npm"}