Release notes

v2.3.0

Released on September 8, 2026.

Compatibility changes

This release includes the following compatibility changes:

• Old connection state events removed

  This release removes the status and connectionStateChange event notifications. To listen for connection state changes, use the linkState event instead.

• Cloud Proxy must be explicitly enabled

  This release no longer automatically falls back to Cloud Proxy. To use Cloud Proxy, explicitly set rtmConfig.cloudProxy to true when initializing the RTM instance. Agora recommends that you give end users an option to enable Cloud Proxy based on your business needs.

• Duplicate instances restricted

  If an active RTM instance already uses the same appId and userId, creating another instance returns RTM_ERROR_DUPLICATE_USER_ID (-10027). Reuse the existing instance, or release the old instance before creating a new one.

Improvements

This release includes the following enhancements:

• You can now enable or disable Presence in Agora Console. Presence is enabled by default. Presence-related configuration and API calls take effect only when Presence is enabled in the console.
• Optimizes reconnection and backoff strategies in weak-network environments, improving connection recovery reliability.
• Adds full-link reporting for login and supports enabling log upload through cloud configuration, improving issue diagnosis.
• Adds available access nodes for Geofencing scenarios, improving service availability.
• Improves the availability of Presence queries after login. If the Presence service is still preparing when login succeeds, the SDK automatically waits and retries getOnlineUsers, getUserChannels, and remote user getState queries once the service becomes available. Your app does not need a fixed delay or a temporary subscription to detect readiness, and existing asynchronous result handling remains unchanged.
• Optimizes Presence member synchronization in large channels. When the number of online users in a channel exceeds 512, the SDK automatically applies a large-channel optimization strategy: it continuously synchronizes details for up to 512 members and reports the total number of online users through PresenceEvent.interval.totalOccupancy. You can still use getOnlineUsers with pagination to query the complete member list and query remote user states as needed. No additional mode-switching code is required.
• If an abnormal disconnection occurs after login, subscription requests made during the disconnection are resent after the connection recovers.

Issues fixed

This release fixes the following issues:

• Calling get immediately after setting or subscribing to Metadata occasionally returned -12001.
• Logging in with an expired token incorrectly reported the linkState reason as rejected. After the fix, the SDK correctly reports token expiration and reflects LOGIN_NOT_AUTHORIZED in linkState.
• Logging in with an invalid token occasionally returned -10016 or The appid is not consistent..
• A user could still be returned by getOnlineUsers for a short period after calling logout.
• Sending a topic message could return -11024 after joining a stream channel topic and remaining idle for about one minute.

v2.2.4

Released on April 23, 2026.

Compatibility changes

This release includes the following compatibility changes:

• Changes to the default private deployment domain format

  This release adds the domainMode property to privateConfig in RTMConfig. In private deployments of Signaling, use this property to configure the domain name format of the Signaling SDK edge node server. The following values are supported:

  • 1 (default): Custom format, for example ip.**
  • 2: Legacy private deployment format, for example ip.edge.**

Improvements

This release includes the following enhancements:

• Improved experience under network fluctuations

  This release comprehensively improves the experience in weak-network and reconnection scenarios:

  • Supports retrying login immediately when the network is disconnected.
  • Supports calling unsubscribeUserMetadata while the network is disconnected.
  • Improves the stability of refreshing tokens during reconnection.

Bug fixes

This release fixes the following issues:

• Calling logout before receiving results from some Signaling API calls occasionally caused the same API call after re-login to return no result.
• Passing a metadata object that exceeds the length limit when calling removeUserMetadata returned an unexpected error.
• Calling getMessages to retrieve binary history messages occasionally returned unexpected content.
• Logging in with a token that has no Signaling privilege returned an unexpected error code or error reason.
• If the App ID bound to the Signaling client instance did not match the App ID used to generate the token, the error code was incorrect.
• If a call to subscribe failed, the returned error code was incorrect.
• Due to a network module issue in Chrome, network state detection was abnormal and Signaling login failed.

v2.2.3

This version was released on November 15, 2025.

Compatibility changes

tokenPrivilegeWillExpire event trigger timing

In previous versions, the SDK triggered the tokenPrivilegeWillExpire event at 30, 20, and 10 seconds before the token expired. Starting from this version, the SDK triggers this event only once, 30 seconds before the token expires. This change simplifies the logic for handling token expiration.

Improvements

• Adds event reporting for Stream Channels to facilitate issue diagnosis.
• Improves the stability of Geo-fencing connections.
• Enhances the reliability of connecting to the Signaling service and reconnecting under poor network conditions.
• Adds IP masking to meet compliance requirements.
• Filters out channel messages that are not expected in business logic.

Issues fixed

This version fixes the following issues:

• In previous versions, after receiving a FAILED event when logging in with the same user ID, you had to call logout before calling login again. This version optimizes the process: after receiving a FAILED event, you can now directly call login to log in again without calling logout first.
• After acquiring a Lock and stopping the subscription, a Lock could not be released.
• Occasionally, the SDK status showed LinkStateConnected, while the Signaling service was actually unavailable.
• Under poor network conditions, the SDK occasionally failed to resume the subscription after reconnecting.
• When subscribing to a channel multiple times, Presence events were incorrect.

v2.2.2

Released on April 30, 2025.

Improvements

This release includes the following improvements:

• New connection state change reason

  Adds a new LOGIN_TOO_FREQUENT reason to RtmLinkStateChangeReason, indicating that login operations are too frequent.

• New token update timeout error code

  To provide feedback on a failed token update operation, this release adds a new error code RTM_RENEW_TOKEN_TIMEOUT with a code of -10026.

• Presence event notification optimization

  When channel data fails to sync properly, the SDK re-triggers a SNAPSHOT event. Upon receiving this event, users can update their app's local cache.

• getUserChannels query setting optimization

  This release allows you to set the userId to an empty string when calling getUserChannels. In this case, the SDK uses the local user's userId for the query.

• Revised error code -10015 reason

  This release revises the reasons for error code RTM_ERROR_LOGIN_NOT_AUTHORIZED (-10015). The error is returned when the service is not enabled, payments are overdue, or the account is banned.

• Additional updates

  • Supports canceling subscription to a specific channel when the user is not logged into Signaling.
  • When calling getOnlineUsers to query users in the current channel, users who have timed out are no longer returned.
  • The SDK no longer generates and uploads new logs without API calls, saving bandwidth.
  • Reconnection logic is optimized.

Issues fixed

This release fixes the following issues:

• Fixes the issue where channel messages could still be received after unsubscribing from the channel.
• Fixes the issue where channel or user metadata could still be retrieved using the get method after being removed.

v2.2.1

Released on December 13, 2024.

New features

1. SDK connection state change reason

   This release adds the RtmLinkStateChangeReason enumeration class to the SDK connection state linkState, to report the reason for the connection state change.

Improvements

This release optimizes the user state of the Presence feature as follows to improve its usability:

• Supports full deletion of state. When calling the removeState method, if you do not set the options parameter, or set the state property of the options parameter to an empty array, the SDK deletes all user states by default.
• The setState and removeState methods support keys containing the [, ], and . characters.
• When the SDK connection state is FAILED, you can call the getState, setState, and removeState methods. In previous versions, the SDK would report an error directly.
• Stream Channel supports restoring user states.
• Fixes some usability issues related to state.

Fixed issues

This release fixes the following issues:

• When the SDK connection state is FAILED, calling the Lock and Storage methods causes the SDK to report an RTM_ERROR_NOT_LOGIN error. This release adjusts the error message. Starting from v2.2.1, the SDK reports an RTM_ERROR_LOGIN_TIMEOUT error.
• The subscription to a channel fails during disconnection, and the subscription state is not reset to unsubscribed after the network recovers.

v2.2.0

Released on September 10, 2024.

Compatibility changes

This release removes the token parameter from the RTMConfig and adds a new token parameter in the login method as a replacement. Update your implementation code accordingly.

• Before v2.2.0

  const { RTM } = AgoraRTM;
  
  const rtmConfig = {
      token : "yourToken",
  
      encryptionMode : "AES_256_GCM",
      salt : yourSalt,
      cipherKey : "yourCipherKey",
      presenceTimeout : 300,
      logUpload : true,
      logLevel : "debug",
      cloudProxy : false,
      useStringUserId : false
      privateConfig: serviceType,
      heartbeatInterval: 5
  };
  const rtm = new RTM("yourAppId", "yourUserId", rtmConfig);
  
  try{
  
      const result = await rtm.login();
  
      console.log(result);
  } catch (status){
      console.log(status);
  }

• After 2.2.0

  // v2.2.0 and later
  const { RTM } = AgoraRTM;
  
  const rtmConfig = {
  
      encryptionMode : "AES_256_GCM",
      salt : yourSalt,
      cipherKey : "yourCipherKey",
      presenceTimeout : 300,
      logUpload : true,
      logLevel : "debug",
      cloudProxy : false,
      useStringUserId : false
      privateConfig: serviceType,
      heartbeatInterval: 5
  };
  const rtm = new RTM("yourAppId", "yourUserId", rtmConfig);
  
  try {
  
      const result = await rtm.login({ token: "your_token" });
  
  } catch (status) {
      const { operation, reason, errorCode } = status;
      console.log(`${operation} failed, the error code is ${errorCode}, because of: ${reason}.`);
  }

New features

1. Private deployment capability

   This release adds the privateConfig parameter in RtmConfig to set private deployment. See Private deployment configuration.

2. Heartbeat interval configuration

   This release adds the heartbeatInterval parameter in RtmConfig to set the interval at which the SDK sends heartbeat packets to the server. See Heartbeat interval and presence timeout parameters.

3. User channel

   This release adds the USER type in RtmChannelType for sending messages to specific users. This feature can replace the peer-to-peer messaging feature in v1. See User channels.

4. Quiet mode configuration

   This release adds the beQuiet property in SubscribeOptions and JoinChannelOptions to enable quiet mode when subscribing to or joining a channel. Once you enable the quiet mode, other users in the channel cannot receive your presence event notifications.

Improvements

1. Connection state management

   This release deprecates the onConnectionStateChanged callback and adds the onLinkStateEvent callback instead. See Connection state transitions and recovery.

2. REMOTE_STATE_CHANGED event notification logic

   This release changes the triggering logic of the REMOTE_STATE_CHANGED event. When a user sets or modifies multiple key-value pairs at once, other users in the channel receive only one event notification.

3. Support for event notification timestamps

   This release adds a new timestamp parameter in the following callbacks to report the timestamp of the triggered event notification:

   • message
   • presence
   • topic
   • storage
   • lock

4. Optimized API behavior

   This release improves the behavior of the following APIs:

   • login
     • Before v2.2.0: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
     • v2.2.0 or later: The SDK supports multiple consecutive calls to this method without the need for additional calls to logout in between. Additionally, when the token parameter is an empty string, the SDK uses the app ID you provided during initialization as a replacement for the token.
   • subscribe
     • Before v2.2.0: The SDK does not support multiple consecutive calls to this method.
     • v2.2.0 or later: The SDK supports multiple consecutive calls to this method.
   • join
     • Before v2.2.0: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
     • v2.2.0 or later: The SDK supports multiple consecutive calls to this method. Additionally, when the token parameter is an empty string, the SDK uses the app ID you provided during initialization as a replacement for the token.

5. Range of presenceTimeout

   This release changes the range of the presenceTimeout parameter in the RtmConfig from [10, 300] to [5, 300].

6. Other improvements

   This release also improves the following:

   • Optimizes the underlying algorithmic capabilities to enhance data synchronization speed.
   • Enables local users to receive event notifications for messages they send, facilitating message transmission verification during the debugging phase.
   • Removes the timeToken parameter from the response objects of all methods.

v2.1.10

Released on July 2, 2024.

Improvements

This release improves the error code prompt for failed login method calls. For example, when you enable token authentication but use an app ID for initialization, the RTM_ERROR_INVALID_TOKEN (-10005) error code is returned during login.

Fixed issues

This release addresses the following issues:

• In use-cases involving frequent setting and retrieving of locks, the user experienced occasional inaccuracies in the lock event notification.
• After reconnecting from a disconnection, the SDK occasionally failed to initialize the presence service when calling the subscribe method.
• Occasional message reception failure in apps developed using the Vite framework.
• After joining a channel and reconnecting from a disconnection, the user failed to receive the lock and storage event notifications.
• Occasional duplicate receipt of the storage event notifications with the UPDATE type when updating the user metadata.
• Occasional duplicate receipt of the lock event notifications with the REMOVED type when removing locks.

v2.1.9

Released on March 12, 2024.

Improvements

This release optimizes the logic of the client-side encryption. When the length of the salt parameter is less than 32 bytes, the SDK automatically pads it with zeros to reach the required length.

Fixed issues

This release fixes the following issues:

• After calling renewToken to renew the token, some services were not functioning correctly, resulting in unexpected disconnection.
• When the duration of disconnection exceeded the configured value of the presenceTimeout parameter, the value of the reason parameter reported in the status event notification was incorrect.
• Under poor network conditions, the SDK occasionally failed to restore subscriptions to the lock and storage services.
• In specific use-cases, calling acquireLock method did not return the result.
• When a local user left the last topic the user joined, remote users occasionally received both the REMOTE_JOIN and REMOTE_LEAVE topic events.
• The messageType parameter types of the messageEvent callbacks.

v2.1.7

Released on January 22, 2024.

Improvements

1. Optimized the processing logic of expired user status data when disconnected and reconnected.

2. Improved the reliability of message transmission in a Stream Channel under weak network conditions.

Fixed issues

• When calling the getOnlineUsers method and setting includedUserId to true, the parameter includedState set to false was missing from the nextPage return value.
• In the case of randomly subscribing to a Topic, what the user message received in the event notification publisher was inconsistent with the actual message sender.
• After repeatedly subscribing to the same channel, unsubscribing or leaving the channel failed.

v2.1.5

Released on December 22, 2023

This release makes changes to the following APIs. Modify your implementation code after upgrading the SDK:

• Change the parameter type of the messageType from string | binary to STRING | BINARY.
• Rename the TokenPrivilegeWillExpire callback to tokenPrivilegeWillExpire.

New features

1. Stream Channel

   Experience seamless, delay-free data flow from one point to another. Stream channel solution refers to a real-time data pipeline that enables the uninterrupted flow of data from one point to another without delay or latency.

2. Pub/Sub

   Embrace asynchronous messaging, enabling instant communication between publishers and subscribers without the need for immediate responses. The pub/sub model is a messaging pattern used in real-time messaging solutions where publishers send messages to channels, and subscribers receive messages from the channels they are subscribed to.

3. Topic

   Effectively manage data streams with topics, enabling seamless communications between users. Topic serves as a data flow management mechanism in the stream channel. It enables users to subscribe to, distribute, and notify events of data streams. Topics allow users to register as message publishers, send messages, and receive messages from subscribed publishers in a channel.

4. Storage

   Storage is important in signaling solutions to ensure reliable message delivery and prevent message loss or drop.

5. Removing Event Listeners

   This release adds the removeEventListener method. You can use it to remove a specified event listener.

6. Interval Mode

   This release supports the interval mode of presence function. When the number of online users in a channel exceeds the specified Announce Max value, the channel enters the interval mode. The SDK triggers the presence event notification at regular intervals and provides aggregated incremental information about user join, leave, timeout, and state changes in the interval property. For more details, see Interval Mode.

Improvements

1. Presence Service

   User and device online/offline and status change notification capabilities get a list of online users in a channel, retrieve the channel list of online users, and dynamically monitor users joining or leaving channels.

   This release also improves the behavior of calling presence APIs when the presence service is not ready. After joining a stream channel or subscribing to a message channel, if the presence service is not ready, the SDK locally stores your operations related to the presence module and sends them out once the presence service becomes ready.

   Additionally, in the return value of the getOnlineUsers method, this release removes the information of timed-out users.

2. Subscribing Message Publisher

   This release improvements the behavior of subscribing to message publishers with invalid user IDs. When calling the subscribeTopic method, if the list of publishers (users property) contains invalid user IDs, the SDK ignores the invalid user IDs and can successfully subscribe to the valid users.

3. Custom Message Type

   This release supports to pass special characters such as Chinese characters into the customType parameter when calling the publish or publishTopicMessage methods.

4. Encryption Salt

   This release allows to omit the salt parameter when setting encryption.

5. State Synchronization

   Ensures that the shared state between devices or systems remains consistent and up to date in real time.

6. Authentication

   Utilize token-based access control, ensuring secure interactions and protecting data.

7. Locks

   Implement locks to maintain the sequence of messages, ensuring your data is processed in a specific order, preventing any data conflicts. When a client accesses a resource, it can acquire a lock on that resource to prevent other clients from accessing it.

8. Logout Optimization

   This release reduces the response time of the logout method.

9. Error Message Optimization

   To facilitate troubleshooting, this release adds error descriptions for each error code and adds error stacks in the error messages of the storage and lock modules. Additionally, this release removes the RTM_ERROR_INVALID_ARGUMENT(-2) and RTM_ERROR_TOO_OFTEN(-12) error codes, and adds the following error codes:

   • RTM_ERROR_LOGIN_NOT_AUTHORIZED(-10015)
   • RTM_ERROR_INCONSISTENT_APPID(-10016)
   • RTM_ERROR_INVALID_CHANNEL_TYPE(-10019)
   • RTM_ERROR_INVALID_ENCRYPTION_PARAMETER(-10020)
   • RTM_ERROR_OPERATION_RATE_EXCEED_LIMITATION(-10021)

   For error code descriptions and troubleshooting ways, see Error Codes.

Fixed issues

This release fixes the following issues:

• The SDK version information was lost in the log file.
• The userId property of the GetStateResponse data type was null.
• After calling the removeState method, the SDK returned the RemoveStateResponse data type before the removing operation.
• Exceptions in poor network scenarios.
• When joining a channel and setting the parameter as withPresence: false, the userId property returned by the getState method was empty.
• During network disconnection and reconnection, any API call failed and returned the RTM_ERROR_NOT_LOGIN(-10002) error code.
• Calling any API of the presence module failed when the client woke up from sleep mode.
• Calling the login method failed when the resource was not loaded.
• If special characters such as Chinese were passed into the API of the presence module, messages sent to the remote client were truncated.