Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Release notes

Updated

Information about changes in each Signaling SDK release.

The Agora Signaling SDK provides a streamlined and stable messaging mechanism for you to quickly implement real-time messaging for various use-cases. See Product overview for more information.

This page contains release notes for each Signaling SDK platform.

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.**

Note

To use private deployment, set domainMode in privateConfig to 2 after upgrading to this version to ensure compatibility. If you omit this parameter or use the default value 1, the SDK may fail to connect to the Signaling server.

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 fixed 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, EncryptionMode } = AgoraRTM;

const rtmConfig = {
    token : "yourToken",

    encryptionMode : 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, EncryptionMode } = AgoraRTM;

const rtmConfig = {

    encryptionMode : 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 fixed 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.

Information

Signaling version 2.x does not support history and peer-to-peer messages in favor of the pub/sub model.

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 fixed 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.

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved