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.

Known issues and limitations

Starting from 2.2.0, the Signaling SDK and RTC SDK (version 4.3.0 or later) both include dynamic library files. If you are using both SDKs, manually delete the dynamic library files of the older version to avoid conflicts.

  • Signaling SDK v2.3.0 dynamic library version: 1.3.5.
  • Signaling SDK v2.2.8 dynamic library version: 1.3.0.
  • Signaling SDK v2.2.7 dynamic library version: 1.3.0.
  • Signaling SDK v2.2.3, v2.2.4, v2.2.5, and v2.2.6 dynamic library version: 1.2.13.
  • Signaling SDK v2.2.2 dynamic library version: 1.0.11.
  • Signaling SDK v2.2.1 dynamic library version: 1.0.11.
  • Signaling SDK v2.2.0 dynamic library version: 1.0.0.17.

v2.3.0

Released on August 6, 2026.

Compatibility changes

This release removes the onConnectionStateChanged callback. To listen for connection state changes, use onLinkStateEvent instead.

Improvements

Included in this release:

  • You can now enable or disable Presence in Agora Console. Presence is enabled by default. If you disable it, calls to Presence APIs and any subscription options that depend on Presence return an error.

  • Adds error codes: RTM_ERROR_PRESENCE_INACTIVE, RTM_ERROR_PRESENCE_PENDING_REQUEST_CANCELLED, RTM_ERROR_PRESENCE_PENDING_REQUEST_EXCEED_LIMITATION, and RTM_ERROR_CHANNEL_SUBSCRIBE_CANCELED. For error code descriptions and solutions, see Error Codes.

  • The Agora Console project creation flow no longer requires you to configure a service region upfront. This is a workflow change only and doesn't affect service quality.

    You must select a region when you enable Message History or Metadata Storage. This selection cannot be changed.

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

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

  • Increases channel subscription speed.

  • Subscription requests made during an abnormal disconnection are now resent automatically after the connection is restored.

Issues fixed

This release fixes the following issues:

  • Connection state notifications could be incorrect when the app switched to the background before logging in.
  • Reconnecting after a network switch could take a long time.

v2.2.8

Released on February 24, 2026.

Issues fixed

This release fixes the following issues:

  • In certain scenarios, abnormal service connection states occurred when an app resumed from the background to the foreground while a network switch was in progress.
  • In some cases, event notifications failed to be delivered properly after setting a temporary user presence state with Presence.

v2.2.6

v2.2.6 was released on November 15, 2025.

New features

Support for IoT device domain allowlist

In IoT scenarios, devices may be restricted by Internet Service Providers (ISPs). To address this limitation, this version adds the ispPolicyEnabled field to RtmConfig. When you set this field to true, the SDK connects only to servers whose domain names or IP addresses have been registered with the ISP and are included in the allowlist.

Improvements

New reconnection timeout configuration

This version adds the reconnectTimeout field to RtmConfig. Use this field to configure the timeout period in seconds for the SDK to return a timeout error during login or reconnection. When the login or reconnection exceeds the configured duration, the SDK reports the current connection state and reason through a callback.

Issues fixed

  • In some scenarios, the token expiration notification was triggered multiple times.
  • In some scenarios, a peer-to-peer message was delivered to the recipient but the sender received a timeout error.
  • In some scenarios, frequently creating and destroying the Signaling engine by repeatedly calling the C++ API caused a crash.
  • In private deployment scenarios, frequent network switching caused abnormal connection states.

v2.2.4

v2.2.4 was released on April 10, 2025.

Improvements

  • New link state change reason

    This release adds the reason LOGIN_TOO_FREQUENT (37) to RtmLinkStateChangeReason, indicating that the current login operation is too frequent.

  • New renew token timeout error code

    To better reflect the result of the renew token operation, this release adds the error code RTM_RENEW_TOKEN_TIMEOUT (10026).

  • Presence event notification optimization

    When channel data fails to sync properly, the SDK retriggers the SNAPSHOT event. Upon receiving this event, you can update the app's local cache.

  • Other improvements

    • Improved reconnection speed of the Signaling service when switching to background or sleep mode.
    • Optimized SDK performance in weak network conditions.
    • Improved selection of access nodes to enhance connection speed.
    • Further optimized the response time of the login service.

Issues fixed

  • The subscription service occasionally did not recover during reconnection.
  • Query results for users in some channels included information about abnormally offline users.
  • Uncaught exceptions in callback functions could cause the SDK to crash.
  • Subscribing to a topic could sometimes return an error indicating that the user was not in the channel.

v2.2.2

v2.2.2 was released on December 13, 2024.

Compatibility changes

  1. SNAPSHOT state trigger timing change

    This release changes the trigger timing of the SNAPSHOT state in the Presence event. Now, as long as the user is in the channel, the SNAPSHOT event may be received again; after receiving it, the user can update their full information to avoid state synchronization issues caused by exceptions.

  2. Lock timeout calculation rule change

    This release changes the calculation rule for the lock (Lock) timeout. Starting from this version, the lock timeout is calculated from the time when the server determines that the user is offline.

New features

  1. SDK connection state change reason

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

Improvements

This release improves the business performance of the basic messaging service during exceptions, avoiding service unavailability caused by the failure of some services.

Fixed issues

This release fixes the following issues:

  • In some use-cases, incorrect token types cause exceptions.
  • In some use-cases, users may receive repeated offline notifications from the same offline user.
  • After logging in from different devices with the same UID, the connection state may be abnormal.
  • When setting the Presence state frequently, data may be abnormal.
  • When the specified service is not activated, joining a channel does not return an error.
  • In some use-cases, abnormal property values may cause crashes.

v2.2.1

v2.2.1 was released on August 9, 2024.

Compatibility changes

This release optimizes the implementation of certain features, which involves renaming, deleting, or modifying the behavior of some APIs. To ensure the proper functioning of your project, modify your implementation after upgrading the SDK.

  1. Initialization

    This release removes the initialize method and adds the initialization parameter to the createAgoraRtmClient method as a replacement. Refer to the sample code below to modify your implementation:

    // Before v2.2.1
// Create a Signaling instance
IRtmClient* rtmClient = createAgoraRtmClient();

RtmConfig config;
config.appId = "your_appid";
config.userId = "your_name";
config.eventHandler = new RtmEventHandler();
// Initialize the Signaling instance
int ret = rtmClient->initialize(config);
if (ret != RTM_ERROR_OK) {
    // Handle initialization error
}
    // v2.2.1 or later
RtmConfig config;
config.appId = "your_appid";
config.userId = "your_name";
config.eventHandler = new RtmEventHandler();
int errorCode = 0;
// Create and initialize the Signaling instance
rtmClient = createAgoraRtmClient(config, errorCode);
if (!rtmClient || errorCode != 0) {
    std::cout << RED <<"error creating rtm service!" << std::endl;
    exit(0);
}

  2. API return values

    This release adds the return values of all methods, except for createAgoraRtmClient, and changes createStreamChannel and release from int to void. Additionally, this release adds the following asynchronous callbacks:

  3. Metadata

    This release removes the createMetadata method. Refer to the sample code below to modify your implementation:

    // Before v2.2.1
IMetadata* metadata = rtmClient->getStorage()->createMetadata();
    // v2.2.1 or later
Metadata data;

  4. Enumerator changes

    This release adds CERTIFICATION_VERIFY_FAILURE(22) in RtmConnectionChangeReason. The values of the STREAM_CHANNEL_NOT_AVAILABLE and INCONSISTENT_APPID change to 23 and 24, respectively.

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. Dual environment configuration

    This release adds the protocolType parameter in RtmConfig to set the network transport protocol. See Connection protocol.

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

  5. Quiet mode configuration

    This release adds the beQuiet property in SubscribeOptions and JoinChannelOptions to enable the 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 management for details.

  2. RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED event notification logic

    This release changes the triggering logic of the RTM_PRESENCE_EVENT_TYPE_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 data structures to report the timestamp of the triggered event notification:

  4. Optimized API behavior

    This release improves the behavior of the following APIs:

    • login
      • Before v2.2.1: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
      • v2.2.1 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.1: The SDK does not support multiple consecutive calls to this method.
      • v2.2.1 or later: The SDK supports multiple consecutive calls to this method.
    • join
      • Before v2.2.1: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
      • v2.2.1 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. Others

    This release also includes the following improvements:

Fixed issues

This release fixes the issue that remote users occasionally did not receive the REMOTE_LEAVE event notification when the local user directly called the logout method without calling the leave method.

v2.1.12

v2.1.12 was released on July 2, 2024.

Improvements

This release includes the following improvements:

  • For data synchronization errors caused by network issues, this release introduces a user logout mechanism, which ensures that the SDK automatically logs out of the Signaling system.
  • Unsubscribing from a message channel during network disconnection will no longer return an error.

Fixed issues

This release fixes the following issues:

  • During a disconnection with the Signaling system under poor network conditions, the user experienced errors when unsubscribing from a message channel.
  • Under poor network conditions, the user occasionally failed to receive callbacks after a successful login.
  • After reconnecting from a disconnection, the user occasionally could not receive the onStorageEvent event notification.
  • After reconnecting from a disconnection, the SDK occasionally failed to restore subscription relationships in the stream channel.
  • Occasional failure to receive topic messages from web clients.

v2.1.11

v2.1.11 was released on May 13, 2024.

Improvements

This release optimizes the response mechanism when subscribing to or joining channels with the withPresence=true setting. If the user does not receive the SNAPSHOT type of onPresenceEvent event notification within 5 seconds, the SDK will report the CHANNEL_PRESENCE_NOT_READY error code in the onJoinResult callback.

Fixed issues

This release fixes the following issues:

  • In specific use-cases, after logging out of the Signaling system and logging back in, occasional failures occurred when subscribing to or joining channels with the withPresence=true setting.
  • In cases where the connection was lost due to network issues and then restored, if the local user actively called the leave method to leave the channel, a remote user occasionally did not receive the REMOTE_TIMEOUT type of the onPresenceEvent event notification.
  • Occasional failures occurred when frequently calling the subscribe and unsubscribe methods.

v2.1.10

v2.1.10 was released on March 11, 2024.

Fixed issues

This release fixes the following issues:

  • When sending messages frequently, message sending occasionally timed out.
  • After calling renewToken to renew the token, some services were not functioning correctly, resulting in unexpected disconnection.

v2.1.9

v2.1.9 was released on February 22, 2024.

This is the first release of the Signaling SDK for C++ v2.x, which brings innovation in functional coverage, performance improvement, and experience optimization.

  • Functional coverage: v2.x covers more business use-cases by introducing functional modules such as channels, messages, topics, presence, storage, and locks. This enables you to focus more on your own business innovation.
  • Performance improvement: v2.x implements a restructured technical architecture and enhances performance through optimized network connections. Our long-term real-time network access capabilities ensure high service quality characterized by low latency, high reliability, extensive concurrency, and robust extensibility.
  • Experience optimization: v2.x redesigns and simplifies the API interface. We have additionally enriched our documentation, including user guides and API references, with extensive sample code to provide you with comprehensive developer resources. These improvements significantly reduce the effort required to understand and integrate the SDK, ultimately enhancing development efficiency.

New features

v2.1.9 provides the following core functional modules:

  1. Initial configuration

    • createAgoraRtmClient: Create an instance of the Signaling client.
    • initialize: Perform the initial configuration as follows:
      • appId: Set the App ID to enable communication between apps with the same ID while isolating apps with different IDs.
      • userId: Set the user ID to distinguish users or devices.
      • areaCode: Set the area code for the geofencing feature.
      • presenceTimeout: Set the presence timeout.
      • context：
        • For Android, it is the context of Android Activity.
        • For Windows, it is the window handle of the app. Once set, this parameter enables you to connect or disconnect the video devices while they are powered.
      • useStringUserId: Set the data type of the user ID, which can be of type string or type uint.
      • eventHandler: Set event listeners.
      • logConfig: Configure the log file size, log file path, and output level.
      • proxyConfig: Configure whether to enable proxy.
      • encryptionConfig: Configure whether to enable encryption.
    • Event handling: Implement event notification for the events such as onMessageEvent, onPresenceEvent, onTopicEvent, onStorageEvent , onLockEvent, onConnectionStateChange, and onTokenPrivilegeWillExpire.
    • login: Log into the Signaling service.
    • logout: Log out of the Signaling service.
    • release: Destroy the Signaling client.

  2. Channel

    In the Signaling real-time network, channels serve as a mechanism for managing data transmission. When a user subscribes to or joins a channel, they can receive messages and events transmitted within the channel with a latency of up to 100 milliseconds. Signaling enables clients to subscribe to hundreds or even thousands of channels. Most Signaling APIs perform operations such as sending, receiving, and encrypting data on a channel basis.

    Signaling includes two types of channels, message channel and stream channel, each offering distinct core capabilities as follows:

    • Message channel:
      • subscribe: Subscribe to the specified message channel and receive messages and event notifications in the channel.
      • unsubscribe: Unsubscribe from the specified message channel and stop receiving messages and event notifications in the channel.
    • Stream channel:
      • createStreamChannel: Create a stream channel instance and then call relevant APIs.
      • join: Join the stream channel and receive messages and event notifications in the channel.
      • leave: Leave the stream channel and stop receiving messages and event notifications in the channel.
      • release: Destroy the stream channel.

    By calling different methods, the SDK triggers different event notifications.

    • The subscribe, unsubscribe, join, and leave methods trigger the onPresenceEvent event notification. Other users in the channel receive the corresponding REMOTE_JOIN and REMOTE_LEAVE event notifications.
    • When calling subscribe and join to subscribe or join a channel, you can choose whether to configure withMessage, withPresence, withMetadata, withLock, and other parameters to enable or disable the monitoring of the corresponding event. To enable the monitoring, you also need to register the corresponding event listener to receive corresponding event notifications.

  3. Message

    The basis of Signaling is the ability to send messages. You can send messages to channels anytime, anywhere, and the messages are delivered within 100 milliseconds. Signaling supports message payloads of both string and byte type.

    Call publish to send a message to the specified message channel. Calling publish triggers the onMessageEvent event notification. If you want to receive messages in the channel, set withMessage to true when calling subscribe and register the event handler for the onMessageEvent event.

  4. Topic

    In stream channels, topics serve as a data flow management mechanism. This feature allows you to subscribe to, distribute, and notify events related to data streams within stream channels. By leveraging topics effectively, you can significantly reduce business complexity and enhance development efficiency. The main functions of topics are as follows:

    • joinTopic: Register as the publisher of this topic to gain the ability to send messages.
    • publishTopicMessage: Send a message to the topic in the stream channel.
    • leaveTopic: Unregister as the message publisher of this topic.
    • subscribeTopic: Subscribe to one or more message publishers of the topic in this channel.
    • unsubscribeTopic: Unsubscribe from this topic or unsubscribe from one or more message publishers in this topic.
    • getSubscribedUserList: Get the list of subscribed publishers in a specific topic.

    Register (joinTopic) and unregister (leaveTopic) as a message publisher trigger the onTopicEvent event notification that is sent to other users in the channel.

caution

Topics exist only in stream channels, not in message channels.

  1. Presence

    Presence provides the ability to monitor the online status and temporary status changes of users. With presence, you can obtain real-time information as follows:

    • Real-time event notification when a user joins or leaves a specified channel.
    • Real-time event notification when the custom temporary user state changes.
    • Query which channels a specified user has joined or subscribed to.
    • Query which users have joined a specified channel and their temporary user state data.

    The following features can be used in both message channels and stream channels:

    • getOnlineUsers: Get real-time information about the number of online users, the list of online users, and their temporary status in a specified channel.
    • getUserChannels: Get real-time information about the list of channels which a specific user joins.
    • setState: Set the temporary status of a user in a specified channel.
    • getState: Get the temporary status of a user in a specified channel.
    • removeState: Remove the temporary status of a user in a specific channel.

    In addition, presence also provides event notification capabilities through the onPresenceEvent. Events such as users joining, leaving, going offline, setting user state, and removing user state are sent as notifications to other users in the channel in real time (Announce Mode) or at regular intervals (Interval Mode). Presence greatly simplifies the implementation of the synchronization logic related to user online and offline status and state changes. This feature helps make your business more stable, real-time, and reliable.

  2. Storage

    The storage feature provides a dynamic database mechanism that allows developers to dynamically set, store, update, and delete channel metadata and user metadata. It also listens to the events generated by changes of channel metadata or user metadata. After calling the createMetadata method to create Metadata, you can perform operations on channel metadata and user metadata based on your specific needs.

    • Channel metadata

      • setChannelMetadata: Set the channel metadata or channel metadata item for a specified channel.
      • getChannelMetadata: Get the channel metadata and channel metadata item for a specified channel.
      • removeChannelMetadata: Remove the channel metadata or channel metadata item for a specified channel.
      • updateChannelMetadata: Update the existing channel metadata or channel metadata item for a specified channel.

      Setting, deleting, and updating channel metadata trigger the onStorageEvent event notification. This feature can greatly optimize your business logic and provide an excellent user experience. Currently, the event notification onStorageEvent carries the complete information of the current channel metadata. It will be optimized in future versions to provide incremental update capabilities.

      Channel metadata also introduces the ability to control locks. When calling APIs to set, delete, or update channel metadata, if the lockName parameter is set, lock verification is enabled. In this case, only the owners of the lock can call the corresponding methods successfully.

    • User Metadata

      • setUserMetadata: Set the user metadata or a user metadata item for a specified user.
      • getUserMetadata: Get the user metadata or a user metadata item for a specified user.
      • removeUserMetadata: Remove the user metadata or a user metadata item for a specified user.
      • updateUserMetadata: Update the existing user metadata or a user metadata item for a specified user.
      • subscribeUserMetadata: Subscribe to event notifications for changes in user metadata or a user metadata item for a specified user.
      • unsubscribeUserMetadata: Unsubscribe from event notifications for changes in user metadata or a user metadata item for a specified user.

      Setting, deleting, and updating user metadata trigger the onStorageEvent event notification. Other users subscribed to this user metadata receive the event notifications. This feature can greatly optimize your business logic and provide an excellent user experience. Currently, the onStorageEvent event notification carries the complete information of the current user metadata. It will be optimized in future versions to provide incremental update capabilities.

    • Compare And Set (CAS) control

      Both channel metadata and user metadata introduce the CAS version control logic, which provides two independent version control fields that you can use according to your business use-case:

      • Enable version number verification for the entire set of channel metadata by setting the revision property through the setMajorRevision method in the Metadata data type.
      • Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class.

      When setting, deleting, or updating channel metadata or user metadata, you can control whether to enable revision verification by using the revision property. The logic is as follows:

      • If revision is set to -1, the CAS validation is not enabled for this call. If the metadata or metadata item already exists, it is overwritten by the latest value. If the metadata or metadata item does not exist, a new metadata or metadata item is created.
      • If revision is set as a positive Uint64 integer, the CAS validation is enabled for this call. If the metadata or metadata item already exists, the value is updated after successful version number validation. If the metadata or metadata item does not exist, the SDK returns an error code.

  3. Lock

    A critical resource can only be used by one process at a time. If different processes share a critical resource, they need to adopt a mutually exclusive approach to prevent interference. Signaling offers a comprehensive set of lock solutions and process control in distributed systems, enabling you to effectively manage competition among users accessing shared resources. Lock provides the following capabilities:

    • setLock: Set a lock for a specified channel.
    • acquireLock: Acquire a specified lock in a specified channel.
    • releaseLock: Release a specified lock in a specified channel.
    • revokeLock: Revoke the ownership of a specific user for a lock in a specified channel to release the lock.
    • getLocks: Get the details of all locks in a specified channel.
    • removeLock: Remove a specified lock in a specified channel.

    The lock setting, acquisition, release, revocation, and deletion operations trigger the corresponding onLockEvent event notification. You can make full use of this feature to optimize the implementation logic of your business.

Improvements

This release optimizes the handling logic for expired user status data during reconnection.

Contact Us

+1 (408) 879-5885

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

AgoraCopyright © 2026 AgoraAll rights reserved