Release notes

Known issues and limitations

Starting from v2.2.0, the Signaling SDK and Video/Voice SDK (version 4.3.0 or later) both include the libaosl.so library. If you use both SDKs, take the following steps to avoid conflicts:

• If you manually integrate the SDK through CDN, manually delete the older version of the libaosl.so library;
• If you integrate the SDK using a dependency management tool, such as Maven or CocoaPods, ensure that the newer version of the libaosl.so library is included in your project.

For more information, see How do I handle issues when integrating the Signaling SDK and Video/Voice SDK simultaneously?

• Signaling SDK v2.3.0 libaosl.so version: 1.3.5.
• Signaling SDK v2.2.8 libaosl.so version: 1.3.0.
• Signaling SDK v2.2.7 libaosl.so version: 1.3.0.
• Signaling SDK v2.2.3, v2.2.4, v2.2.5, and v2.2.6 libaosl.so version: 1.2.13.
• Signaling SDK v2.2.2 libaosl.so version: 1.0.11.
• Signaling SDK v2.2.1 libaosl.so version: 1.0.11.
• Signaling SDK v2.2.0 libaosl.so 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: PRESENCE_INACTIVE, PRESENCE_PENDING_REQUEST_CANCELLED, PRESENCE_PENDING_REQUEST_EXCEED_LIMITATION, and 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.IntervalInfo.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.

Improvements

Included in this release:

• The Android Maven package name has changed from io.agora:agora-rtm to io.agora.rtm:rtm-sdk. Update your build.gradle dependency as follows:

  implementation 'io.agora.rtm:rtm-sdk:x.y.z'

• A lite version to resolve integration issues when co-integrating with the RTC SDK. For details, see Handle issues when integrating the Signaling SDK and Video/Voice SDK simultaneously.

  implementation 'io.agora.rtm:rtm-sdk-lite:2.2.8'

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.
• On some device models running Android 16, the permission request occasionally exceeded the necessary scope.

v2.2.6

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 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 changes

   This release modifies the trigger timing of the SNAPSHOT event in the Presence event. Now, as long as the user is in the channel, they may receive the SNAPSHOT event again; after receiving it, the user can update their full information to avoid state inconsistencies caused by exceptions.

2. Lock timeout calculation rule changes

   This release modifies the calculation rule of 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.

2. Support 16 KB page size

   Starting from Android 15, the system supports a 16 KB page size. For more information, see Support 16 KB page size. Starting from this version, the SDK supports a 16 KB page size to ensure seamless operation on devices using 4 KB and 16 KB page sizes, improving compatibility and avoiding crashes.

Improvements

This release improves the 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 user who has gone offline.
• 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 the following 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.

• Removes the createMetadata method. Refer to the sample code below to modify your implementation:

  // Before v2.2.1
  Metadata metadata = rtmClient.getStorage().createMetadata();

  // v2.2.1 or later
  Metadata metadata = new Metadata();

• Removes the StateItem class, and changes the type of the following parameters from ArrayList<StateItem> to HashMap<String, String>:

  • The items parameter of the setState method.
  • The stateItems parameter of the PresenceEvent class.
  • The states parameter of the UserState class.

• Adds CERTIFICATION_VERIFY_FAILURE(22) in RtmConnectionChangeReason. The values of 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 quiet mode when subscribing 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. 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 data structures to report the timestamp of the triggered event notification:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

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. Other improvements

   This release also enhances the underlying algorithm capability to improve the data synchronization speed.

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 resultCallback parameter.

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, the 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.

Compatibility changes

This release improves message publishing options as follows:

• Removes the sendTs parameter and adds the channelType parameter in PublishOptions. See details in PublishOptions.
• Modifies the type of the options parameter in the publishTopicMessage method from PublishOptions to TopicMessageOptions. See details in TopicMessageOptions.

Make sure to modify the implementation of the relevant features after upgrading the SDK.

Improvements

This release adds the following improvements:

• Adds error codes: INVALID_CHANNEL_TYPE, RTM_ERROR_INVALID_ENCRYPTION_PARAMETER, and RTM_ERROR_OPERATION_RATE_EXCEED_LIMITATION. For error code descriptions and solutions, see Error Codes.
• Optimizes the handling logic for expired user status data during reconnection.

Fixed issues

This release fixes the occasional crash issue when calling the getOnlineUsers method to retrieve paginated results.

v2.1.7

v2.1.7 was released on January 22, 2024.

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.

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.

Known issues and limitations

v2.3.0

Released on August 6, 2026.

Compatibility changes

This release removes the legacy connection state callback. To listen for connection state changes, use didReceiveLinkStateEvent 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: presenceInactive/AgoraRtmErrorPresenceInactive, presencePendingRequestCancelled/AgoraRtmErrorPresencePendingRequestCancelled, presencePendingRequestExceedLimitation/AgoraRtmErrorPresencePendingRequestExceedLimitation, and channelSubscribeCanceled/AgoraRtmErrorChannelSubscribeCanceled. 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 AgoraRtmPresenceEvent.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.

• Optimizes how some configuration parameters are used.

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.

Improvements

Included in this release:

• The iOS CocoaPods pod name has changed from AgoraRtm_iOS to AgoraRtm. The new repository supports Mac, visionOS, and iOS architectures simultaneously.

• Adds a ['RtmKit'] subspec version to resolve integration issues when co-integrating with the RTC SDK. For details, see Handle issues when integrating the Signaling SDK and RTC SDK simultaneously.

  pod 'AgoraRtm', 'x.y.z', :subspecs => ['RtmKit']

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

Released on November 15, 2025.

v2.2.4

v2.2.4 was released on April 10, 2025.

v2.2.2

v2.2.2 was released on December 13, 2024.

v2.2.1

v2.2.1 was released on August 9, 2024.

Compatibility changes

This release optimizes the implementation of the following 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.

• Removes the createMetadata method. Refer to the sample code below to modify your implementation:

  // Before v2.2.1
  AgoraRtmMetadata* metadata = [[rtm getStorage] createMetadata];

  // v2.2.1 or later
  AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

• Removes the AgoraRtmStateItem class and changes the type of the following parameters from NSArray<AgoraRtmStateItem *> to NSDictionary:

  • The items parameter of the setState method.
  • The states parameter of the PresenceEvent class.
  • The states parameter of the UserState class.

• Adds CERTIFICATION_VERIFY_FAILURE(22) in RtmConnectionChangeReason. The values of STREAM_CHANNEL_NOT_AVAILABLE and INCONSISTENT_APPID change to 23 and 24, respectively.

New features

1. VisionOS support

   This release adds support for VisionOS. For the minimum supported version and target architecture, see Supported platforms. This release also changes the package name from AgoraRtm_iOS to AgoraRtm. After upgrading the SDK, if you use Cocoapods to integrate the SDK, modify the Podfile file as follows:

   platform :ios, '11.0'
   target 'Your App' do
   pod 'AgoraRtm', '2.2.0'
   end

2. Private deployment capability

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

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

4. Dual environment configuration

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

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

6. Quiet mode configuration

   This release adds beQuiet in SubscribeOptions, and beQuiet in JoinChannelOptions to enable quiet mode when subscribing 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. AgoraRtmPresenceEventTypeRemoteStateChanged event notification logic

   This release changes the triggering logic of the AgoraRtmPresenceEventTypeRemoteStateChanged 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:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

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 than 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 enhances the underlying algorithm capability to improve data synchronization speed.

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

New privacy information file

To meet Apple's security and compliance requirements for app distribution, this release adds a PrivacyInfo.xcprivacy file. It contains API call instructions for accessing or using user data within the SDK, as well as descriptions of the data types collected by the SDK.

Other improvements

This release optimizes the response mechanism when subscribing to channels with the withPresence setting or joining channels with the withPresence 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 completionBlock parameter.

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 channels with the withPresence setting or joining channels with the withPresence 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.

Compatibility changes

This release improves message publishing options as follows:

• Removes the sendTs parameter, and adds the channelType parameter in AgoraRtmPublishOptions. See details in AgoraRtmPublishOptions.
• Modifies the type of the options parameter in the publishTopicMessage method from AgoraRtmPublishOptions to AgoraRtmTopicMessageOptions. See details in AgoraRtmTopicMessageOptions.

Improvements

This release adds the following improvements:

• Adds error codes: AgoraRtmErrorInvalidChannelType, AgoraRtmErrorInvalidEncryptionParameter, and AgoraRtmErrorOperationRateExceedLimitation. For error code descriptions and solutions, see Error Codes.
• Optimizes the handling logic for expired user status data during reconnection.

Fixed issues

This release fixes the following issues:

• The initialization process did not return a failure when the encryptionKdfSalt parameter length was not 32 bytes.
• Occasional crashes occurred when calling the getOnlineUsers method to retrieve paginated results.
• The memory leak issue during initialization.

v2.1.7

v2.1.7 was released on January 22, 2024.

Compatibility changes

If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.

1. Initialization parameters

   To remind users to set the required parameters during initialization, this release adds the following methods:

   • The init method in AgoraRtmMetadata, which prevents users from initializing without providing the required parameters.
   • The init and initWithServer methods in AgoraRtmProxyConfig, which require users to provide the server, port, and proxyType parameters during initialization.
   • The init and initWithAppId methods in AgoraRtmClientConfig, which require users to provide the appId and userId parameters during initialization.

2. Channel options

   This release adds the following changes to the AgoraRtmJoinChannelOption and AgoraRtmSubscribeOptions classes:

   • Removes the withMetadata, withPresence, and withLock parameters from the AgoraRtmJoinChannelOption class, and adds a features parameter as a replacement. You can set one or more event notifications in the features parameter based on your needs.
   • Removes the withMessage, withMetadata, withPresence, and withLock parameters from the AgoraRtmSubscribeOptions class, and adds a features parameter as a replacement. You can set one or more event notifications in the features parameter based on your needs.

   This release also improves the performace of setting the presence event notification in AgoraRtmJoinChannelOption.

3. Naming changes

   This release renames the following callbacks:

   Before v2.1.6	v2.1.6
   onMessageEvent	didReceiveMessageEvent
   onPresenceEvent	didReceivePresenceEvent
   onLockEvent	didReceiveLockEvent
   onStorageEvent	didReceiveStorageEvent
   onTopicEvent	didReceiveTopicEvent
   onTokenPrivilegeWillExpire	tokenPrivilegeWillExpire
   connectionStateChanged	connectionChangedToState

   This release also renames the items parameter of the removeState method to keys, and changes the type of the areaCode parameter from unsigned int to AgoraRtmAreaCode.

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.

7. Multiple ways to add event listeners

   This release adds the addDelegate and removeDelegate methods. In addition to adding or removing an event listener object during initialization, you can also call the new methods to add or remove one or more event listener objects at any time during the app's lifecycle.

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

Improvements

1. Message sending

   This release adds two new methods, publish and publishTopicMessage, which have the same name as existing methods. Additionally, this release changes the type of the message parameter in the original methods. See details as follows:

   // Before v2.1.6
   // The type of the message parameter is NSObject
   // The NSObject type supports passing both string and binary messages
   - (void) publish: (NSString* _Nonnull)channelName
               message: (NSObject* _Nonnull)message
               withOption: (AgoraRtmPublishOptions* _Nullable)publishOption
               completion: (AgoraRtmOperationBlock _Nullable)completionBlock;
   
   - (void) publishTopicMessage: (NSObject * _Nonnull) message
               inTopic: (NSString * _Nonnull) topic
               withOption:(AgoraRtmPublishOptions * _Nullable) options
               completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

   // v2.1.6
   // The type of the message parameter is NSString or NSData
   // The NSString type only supports passing string data
   // The NSData type only supports passing binary data
   
   // publish[1/2]
   - (void) publish:(NSString* _Nonnull)channelName
           message:(NSString* _Nonnull)message
           option:(AgoraRtmPublishOptions* _Nullable)publishOption
       completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publish[2/2]
   - (void) publish:(NSString* _Nonnull)channelName
               data:(NSData* _Nonnull)data
           option:(AgoraRtmPublishOptions* _Nullable)publishOption
       completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publishTopicMessage[1/2]
   - (void) publishTopicMessage:(NSString * _Nonnull)topic
                       message:(NSString * _Nonnull)message
                       option:(AgoraRtmPublishOptions * _Nullable)options
                   completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publishTopicMessage[2/2]
   - (void) publishTopicMessage:(NSString * _Nonnull)topic
                           data:(NSData * _Nonnull)data
                       option:(AgoraRtmPublishOptions * _Nullable)options
                   completion:(AgoraRtmOperationBlock _Nullable)completionBlock

2. Message receiving

   This release removes the getData method, getType method, and AgoraRtmMessageType class in the AgoraRtmMessage class, and adds the rawData and stringData properties instead. You can use the rawData property to receive binary messages, and the stringData property to receive string messages.

3. Response and error message optimization

   This release changes the information returned by the completionBlock callback function in various methods:

   • If the method call is successful, the response parameter returns the corresponding data, and the errorInfo parameter returns nil.
   • If the method call fails, the response parameter returns nil, and the errorInfo parameter returns the corresponding error message.

   Additionally, this release adds an error parameter to the initWithConfig and createStreamChannel methods. If the method call fails, you can see the output error description in the error parameter.

Fixed issues

This release fixes the following issues:

• Occasional inability to log out of Signaling when the network status changed.
• Occasional inability to log in to Signaling after logging out when the network status changed.
• When the network was disconnected, users occasionally did not receive the Snapshot event notification due to that the app did not clear data.
• When a user joined a channel and switched the app to the background and then back to the foreground, the SDK occasionally triggered the REMOTE_JOIN event notification multiple times.

Known issues and limitations

v2.3.0

Released on August 6, 2026.

Compatibility changes

This release removes the legacy connection state callback. To listen for connection state changes, use didReceiveLinkStateEvent 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: presenceInactive/AgoraRtmErrorPresenceInactive, presencePendingRequestCancelled/AgoraRtmErrorPresencePendingRequestCancelled, presencePendingRequestExceedLimitation/AgoraRtmErrorPresencePendingRequestExceedLimitation, and channelSubscribeCanceled/AgoraRtmErrorChannelSubscribeCanceled. 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 AgoraRtmPresenceEvent.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.

• Optimizes how some configuration parameters are used.

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.

Improvements

Included in this release:

• The iOS CocoaPods pod name has changed from AgoraRtm_iOS to AgoraRtm. The new repository supports Mac, visionOS, and iOS architectures simultaneously.

• Adds a ['RtmKit'] subspec version to resolve integration issues when co-integrating with the RTC SDK. For details, see Handle issues when integrating the Signaling SDK and RTC SDK simultaneously.

  pod 'AgoraRtm', 'x.y.z', :subspecs => ['RtmKit']

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

Released on November 15, 2025.

v2.2.4

v2.2.4 was released on April 10, 2025.

v2.2.2

v2.2.2 was released on December 13, 2024.

v2.2.1

v2.2.1 was released on August 9, 2024.

Compatibility changes

This release optimizes the implementation of the following 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.

• Removes the createMetadata method. Refer to the sample code below to modify your implementation:

  // Before v2.2.1
  AgoraRtmMetadata* metadata = [[rtm getStorage] createMetadata];

  // v2.2.1 or later
  AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

• Removes the AgoraRtmStateItem class and changes the type of the following parameters from NSArray<AgoraRtmStateItem *> to NSDictionary:

  • The items parameter of the setState method.
  • The states parameter of the PresenceEvent class.
  • The states parameter of the UserState class.

• Adds CERTIFICATION_VERIFY_FAILURE(22) in RtmConnectionChangeReason. The values of STREAM_CHANNEL_NOT_AVAILABLE and INCONSISTENT_APPID change to 23 and 24, respectively.

New features

1. VisionOS support

   This release adds support for VisionOS. For the minimum supported version and target architecture, see Supported platforms. This release also changes the package name from AgoraRtm_iOS to AgoraRtm. After upgrading the SDK, if you use Cocoapods to integrate the SDK, modify the Podfile file as follows:

   platform :ios, '11.0'
   target 'Your App' do
   pod 'AgoraRtm', '2.2.0'
   end

2. Private deployment capability

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

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

4. Dual environment configuration

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

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

6. Quiet mode configuration

   This release adds beQuiet in SubscribeOptions, and beQuiet in JoinChannelOptions to enable quiet mode when subscribing 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. AgoraRtmPresenceEventTypeRemoteStateChanged event notification logic

   This release changes the triggering logic of the AgoraRtmPresenceEventTypeRemoteStateChanged 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:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

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 than 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 enhances the underlying algorithm capability to improve data synchronization speed.

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

New privacy information file

To meet Apple's security and compliance requirements for app distribution, this release adds a PrivacyInfo.xcprivacy file. It contains API call instructions for accessing or using user data within the SDK, as well as descriptions of the data types collected by the SDK.

Other improvements

This release optimizes the response mechanism when subscribing to channels with the withPresence setting or joining channels with the withPresence 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 completionBlock parameter.

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 channels with the withPresence setting or joining channels with the withPresence 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.

Compatibility changes

This release improves message publishing options as follows:

• Removes the sendTs parameter, and adds the channelType parameter in AgoraRtmPublishOptions. See details in AgoraRtmPublishOptions.
• Modifies the type of the options parameter in the publishTopicMessage method from AgoraRtmPublishOptions to AgoraRtmTopicMessageOptions. See details in AgoraRtmTopicMessageOptions.

Improvements

This release adds the following improvements:

• Adds error codes: AgoraRtmErrorInvalidChannelType, AgoraRtmErrorInvalidEncryptionParameter, and AgoraRtmErrorOperationRateExceedLimitation. For error code descriptions and solutions, see Error Codes.
• Optimizes the handling logic for expired user status data during reconnection.

Fixed issues

This release fixes the following issues:

• The initialization process did not return a failure when the encryptionKdfSalt parameter length was not 32 bytes.
• Occasional crashes occurred when calling the getOnlineUsers method to retrieve paginated results.
• The memory leak issue during initialization.

v2.1.7

v2.1.7 was released on January 22, 2024.

Compatibility changes

If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.

1. Initialization parameters

   To remind users to set the required parameters during initialization, this release adds the following methods:

   • The init method in AgoraRtmMetadata, which prevents users from initializing without providing the required parameters.
   • The init and initWithServer methods in AgoraRtmProxyConfig, which require users to provide the server, port, and proxyType parameters during initialization.
   • The init and initWithAppId methods in AgoraRtmClientConfig, which require users to provide the appId and userId parameters during initialization.

2. Channel options

   This release adds the following changes to the AgoraRtmJoinChannelOption and AgoraRtmSubscribeOptions classes:

   • Removes the withMetadata, withPresence, and withLock parameters from the AgoraRtmJoinChannelOption class, and adds a features parameter as a replacement. You can set one or more event notifications in the features parameter based on your needs.
   • Removes the withMessage, withMetadata, withPresence, and withLock parameters from the AgoraRtmSubscribeOptions class, and adds a features parameter as a replacement. You can set one or more event notifications in the features parameter based on your needs.

   This release also improves the performace of setting the presence event notification in AgoraRtmJoinChannelOption.

3. Naming changes

   This release renames the following callbacks:

   Before v2.1.6	v2.1.6
   onMessageEvent	didReceiveMessageEvent
   onPresenceEvent	didReceivePresenceEvent
   onLockEvent	didReceiveLockEvent
   onStorageEvent	didReceiveStorageEvent
   onTopicEvent	didReceiveTopicEvent
   onTokenPrivilegeWillExpire	tokenPrivilegeWillExpire
   connectionStateChanged	connectionChangedToState

   This release also renames the items parameter of the removeState method to keys, and changes the type of the areaCode parameter from unsigned int to AgoraRtmAreaCode.

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.

7. Multiple ways to add event listeners

   This release adds the addDelegate and removeDelegate methods. In addition to adding or removing an event listener object during initialization, you can also call the new methods to add or remove one or more event listener objects at any time during the app's lifecycle.

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

Improvements

1. Message sending

   This release adds two new methods, publish and publishTopicMessage, which have the same name as existing methods. Additionally, this release changes the type of the message parameter in the original methods. See details as follows:

   // Before v2.1.6
   // The type of the message parameter is NSObject
   // The NSObject type supports passing both string and binary messages
   - (void) publish: (NSString* _Nonnull)channelName
               message: (NSObject* _Nonnull)message
               withOption: (AgoraRtmPublishOptions* _Nullable)publishOption
               completion: (AgoraRtmOperationBlock _Nullable)completionBlock;
   
   - (void) publishTopicMessage: (NSObject * _Nonnull) message
               inTopic: (NSString * _Nonnull) topic
               withOption:(AgoraRtmPublishOptions * _Nullable) options
               completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

   // v2.1.6
   // The type of the message parameter is NSString or NSData
   // The NSString type only supports passing string data
   // The NSData type only supports passing binary data
   
   // publish[1/2]
   - (void) publish:(NSString* _Nonnull)channelName
           message:(NSString* _Nonnull)message
           option:(AgoraRtmPublishOptions* _Nullable)publishOption
       completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publish[2/2]
   - (void) publish:(NSString* _Nonnull)channelName
               data:(NSData* _Nonnull)data
           option:(AgoraRtmPublishOptions* _Nullable)publishOption
       completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publishTopicMessage[1/2]
   - (void) publishTopicMessage:(NSString * _Nonnull)topic
                       message:(NSString * _Nonnull)message
                       option:(AgoraRtmPublishOptions * _Nullable)options
                   completion:(AgoraRtmOperationBlock _Nullable)completionBlock
   
   // publishTopicMessage[2/2]
   - (void) publishTopicMessage:(NSString * _Nonnull)topic
                           data:(NSData * _Nonnull)data
                       option:(AgoraRtmPublishOptions * _Nullable)options
                   completion:(AgoraRtmOperationBlock _Nullable)completionBlock

2. Message receiving

   This release removes the getData method, getType method, and AgoraRtmMessageType class in the AgoraRtmMessage class, and adds the rawData and stringData properties instead. You can use the rawData property to receive binary messages, and the stringData property to receive string messages.

3. Response and error message optimization

   This release changes the information returned by the completionBlock callback function in various methods:

   • If the method call is successful, the response parameter returns the corresponding data, and the errorInfo parameter returns nil.
   • If the method call fails, the response parameter returns nil, and the errorInfo parameter returns the corresponding error message.

   Additionally, this release adds an error parameter to the initWithConfig and createStreamChannel methods. If the method call fails, you can see the output error description in the error parameter.

Fixed issues

This release fixes the following issues:

• Occasional inability to log out of Signaling when the network status changed.
• Occasional inability to log in to Signaling after logging out when the network status changed.
• When the network was disconnected, users occasionally did not receive the Snapshot event notification due to that the app did not clear data.
• When a user joined a channel and switched the app to the background and then back to the foreground, the SDK occasionally triggered the REMOTE_JOIN event notification multiple times.

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

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:

   • onPublishTopicMessageResult
   • onUnsubscribeTopicResult
   • onGetSubscribedUserListResult
   • onUnsubscribeResult
   • onLogoutResult
   • onRenewTokenResult
   • onUnsubscribeUserMetadataResult

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:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

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:

   • Enhances the underlying algorithm capability to improve data synchronization speed.

   • Adds the requestId parameter to the following methods:

     • login
     • logout
     • renewToken
     • unsubscribe

   • Adds the errorCode parameter to the createStreamChannel method.

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.

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.

v2.3.0

Released on September 2, 2026.

This is the first release of the Signaling SDK for Linux Java. This release includes the following features:

• Message channels: Publish and subscribe to messages using the industry-standard Pub/Sub model, with no limit on the number of publishers or subscribers in a channel.
• User channels: Send and receive point-to-point messages by specifying a user ID directly, without subscribing to a channel.
• Stream channels and topics: Create stream channels and organize data streams into topics, with optional timestamp synchronization against RTC audio and video streams.
• Presence: Query online users and their channels, and set, get, and remove temporary user state.
• Storage: Set, get, remove, and subscribe to channel and user metadata.
• Lock: Set, acquire, release, revoke, and remove distributed locks on a channel.
• Link state and token events: Receive event notifications for connection state changes and upcoming token expiration through onLinkStateEvent and onTokenPrivilegeWillExpire.

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:

   • onPublishTopicMessageResult
   • onUnsubscribeTopicResult
   • onGetSubscribedUserListResult
   • onUnsubscribeResult
   • onLogoutResult
   • onRenewTokenResult
   • onUnsubscribeUserMetadataResult

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:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

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:

   • Enhances the underlying algorithm capability to improve data synchronization speed.

   • Adds the requestId parameter to the following methods:

     • login
     • logout
     • renewToken
     • unsubscribe

   • Adds the errorCode parameter to the createStreamChannel method.

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.

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.

Known issues and limitations

v2.2.5

v2.2.5 was released on September 25, 2025.

Compatibility changes

• Snapshot event trigger timing

  The Snapshot event in Presence events can now be triggered again as long as a user is in the channel. After receiving it, update the complete information to avoid state synchronization issues caused by exceptions.

• Lock expiration time calculation

  Lock expiration time is now calculated from when the server determines that the user is offline.

New features

• SDK connection state change reason Added the RtmLinkStateChangeReason enumeration to the LinkStateEvent, reporting the reason for connection state changes.

• IoT device domain whitelist Added the ispPolicyEnabled field to RtmConfig. When set to true, the SDK connects only to servers in the domain or IP whitelist registered with carriers, helping IoT devices bypass ISP restrictions.

• 16 KB memory page size support (Android) Starting with Android 15, the system supports 16 KB memory page sizes. This version adds SDK support for 16 KB pages to ensure stability and performance across devices using 4 KB or 16 KB page sizes, improving compatibility and preventing crashes. See support 16 KB page sizes.

Improvements

• Adds token renewal timeout error code

  To provide feedback on token renewal operation results, this version adds error code renewTokenTimeout (-10026).

• Optimizes presence event notification

  When channel data could not be synchronized, the SDK triggers a Snapshot event again. After receiving this event, users can update their app's local cache.

• Other improvements

  • Improved login service duration.
  • Increased Signaling service recovery and reconnection speed after backgrounding or hibernation.
  • Optimized SDK performance under weak network conditions.
  • Optimized access node selection to speed up service connections.
  • Improved basic message service performance during service exceptions to avoid message unavailability.

Issues fixed

• Token expiration notifications was triggered multiple times.
• Point-to-point messages were delivered to the peer, but the sender received a timeout response.
• On iOS, exiting the app sometimes caused Signaling SDK crashes
• In private deployment scenarios, frequent network switching caused connection state exceptions.
• In callback functions, if business code had uncaught exceptions, it caused SDK crashes.
• When subscribing to topics, a "not joined channel" error was returned.
• Occasionally during reconnection, subscription services were not restored.
• When querying some channel users, results included information from abnormally offline users.
• Incorrect token types caused abnormal errors.
• Users received multiple offline notifications for the same offline user.
• After the same UID logged in from different endpoints, connection state exceptions occurred.
• Frequent Presence state updates caused data exceptions.
• When specified services were not enabled, joining channels did not return errors.
• In some scenarios, abnormal property values caused crash issues.

v2.2.1

v2.2.1 was released on October 15, 2024.

This is the first release of the Signaling SDK v2.x for Flutter, 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 also expanded 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.2.1 provides the following core functional modules:

1. Initial configuration

   The initial configuration of the Signaling client involves pre-defining or configuring key parameters that influence its subsequent behaviors. Additionally, it offers functions such as login and logout. The core features of the Signaling client are as follows:

   • Future<(RtmStatus, RtmClient)> RTM(...): Create an instance of the Signaling client and configure it in the following way:
     • 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.
     • protocolType: Set the protocol type for message transmission.
     • presenceTimeout: Set the delay imposed by the Signaling server before sending a REMOTE_TIMEOUT event notification to other users once it determines that a client has timed out.
     • heartbeatInterval: Set the time interval at which the client sends heartbeat packets to the Signaling server.
     • useStringUserId: Set the data type of the user ID, which can be of type String or Int.
     • 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, onLinkStateEvent, 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 three types of channels, message channel, user 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.
   • User channel: Users can directly send messages to a specified user without subscribing to a channel. To receive messages, users only need to listen to the message event.
   • 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 Join and 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 Binary type.

   Call publish to send a message to the specified message channel or user 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.

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 all kinds of 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.

   • Channel metadata:

     • setChannelMetadata: Set the channel metadata or metadata item for a specified channel.
     • getChannelMetadata: Get the channel metadata and metadata item for a specified channel.
     • removeChannelMetadata: Remove the channel metadata or metadata item for a specified channel.
     • updateChannelMetadata: Update the existing channel metadata or 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 metadata item for a specified user.
     • getUserMetadata: Get the user metadata or a metadata item for a specified user.
     • removeUserMetadata: Remove the user metadata or a metadata item for a specified user.
     • updateUserMetadata: Update the existing user metadata or a metadata item for a specified user.
     • subscribeUserMetadata: Subscribe to event notifications for changes in user metadata or a metadata item for a specified user.
     • unsubscribeUserMetadata: Unsubscribe from event notifications for changes in user metadata or a 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 majorRevision property.
     • 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 majorRevision or 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 majorRevision or revision is set as a positive int 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.

v2.2.4

Released on July 9, 2025.

This is the first release of the Signaling SDK for React Native 2.x, which brings innovation in functional coverage, performance improvement, and experience optimization.

• Functional coverage: v2.x covers more business scenarios 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.2.4 provides the following core functional modules:

Initial configuration

The initial configuration of the Signaling client involves pre-defining or configuring key parameters that influence its subsequent behaviors. Additionally, it offers functions such as login and logout. The core competencies of the Signaling client are as follows:

• 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 geo-fencing 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, onLockEvent, onStorageEvent, onConnectionStateChanged, and onTokenPrivilegeWillExpire.
• login: Log into the Signaling service.
• logout: Log out of the Signaling service.
• release: Destroy the Signaling client.

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

When you call 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 RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL and RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL 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.

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.

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.

The joinTopic and leaveTopic operations trigger onTopicEvent event notifications that are broadcast to other users in the channel.

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.

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 an RtmMetadata, 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 scenario:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the RtmMetadata class.
• Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class within the RtmMetadata class.

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

• If majorRevision or 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 majorRevision or 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.

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.

v2.1.9

v2.1.9 was released on February 22, 2024.

This is the first release of the Signaling SDK for Unity 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: We have revamped and streamlined our APIs to support the widely adopted Async/Await programming model in the industry. Additionally, we have 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.

Compatibility changes

This release improves the following features, ensure that you modify the implementation of the relevant features after upgrading the SDK.

• Message publish options

  This release optimizes the options parameter of the PublishAsync and PublishTopicMessageAsync methods as follows:

  • Removes the sendTs parameter, and adds the channelType parameter in PublishOptions of the PublishAsync method. See details in PublishOptions.
  • Modify the type of the options parameter in the PublishTopicMessageAsync method from PublishOptions to TopicMessageOptions. See details in TopicMessageOptions.

• Connection state callback renaming

  This release changes the name of the onConnectionStateChange callback to onConnectionStateChanged.

New features

v2.1.9 provides the following core functional modules:

1. Initial configuration

   The initial configuration of the Signaling client involves pre-defining or configuring key parameters that influence its subsequent behaviors. Additionally, it offers functions such as login and logout. The core competencies of the Signaling client are as follows:

   • createAgoraRtmClient: Create an instance of the Signaling client and 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 geo-fencing feature.
     • presenceTimeout: Set the presence timeout.
     • useStringUserId: Set the data type of the user ID, which can be of type string or type uint.
     • 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, onConnectionStateChanged, 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 Join and 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 binary 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.

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

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.

   • 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 majorRevision property in the Metadata class.
     • Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class within the RtmMetadata class.

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

     • If majorRevision or 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 majorRevision or revision is set as a positive Int64 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.

4. This release adds the GetOnlineUsersAsync method to replace the WhoNowAsync method, and the GetUserChannelsAsync method to replace the WhereNowAsync method.

Improvements

• Error codes

  This release adds the following error codes: INVALID_CHANNEL_TYPE, INVALID_ENCRYPTION_PARAMETER, and OPERATION_RATE_EXCEED_LIMITATION. For error code descriptions and solutions, see Error Codes.

• Presence

  This release optimizes the handling logic for expired user status data during reconnection, and improves the performance of setting the presence event notification in JoinChannelOptions.

• Others

  This release optimizes memory performance and fixes the potential memory leak issue.

Fixed issues

This release fixes the following issues:

• Occasional crash when calling the WhoNowAsync method to retrieve paginated results.
• Occasional packet loss of presence data in specific use-cases.
• Failure to trigger asynchronous callbacks after method calls in specific use-cases.
• Crash caused by invalid parameters when using client-side encryption.
• Occasional inability to log in to or log out of the Signaling system when the network status changed.
• When the network was disconnected, users occasionally did not receive the SNAPSHOT event notification due to that the app did not clear data.
• When a user joined a channel and switched the app to the background and then back to the foreground, the SDK occasionally triggered the REMOTE_JOIN event notification multiple times.