Release notes

Agora will soon stop the service for the following features. If you have not implemented these features, best practice is not to.

• Send and Receive Image or File Messages
• Historical messages
• Offline messages

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

This page contains information on the following releases:

v1.5.1 was released on September 1, 2022 and improved the stability of the SDK.

v1.5.0 was released on July 27, 2022.

Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them.

The following methods are deprecated:

• createFileMessageByMediaId
• createFileMessageByUploading
• createImageMessageByMediaId
• createImageMessageByUploading
• cancelMediaUpload
• cancelMediaDownload
• downloadMediaToFile
• downloadMediaToMemory
• onFileMessageReceived
• onFileMessageReceivedFromPeer
• onImageMessageReceived
• onImageMessageReceivedFromPeer
• onMediaUploadingProgress
• onMediaDownloadingProgress
• enableOfflineMessaging
• enableHistoricalMessaging

v1.4.10 was released on March 01, 2022.

As of v1.4.10, You don’t need to add the following permission to the AndroidManifest.xml file of an Android project:

_1

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Fixed some rich media related crashes.

v1.4.9 was released on November 19, 2021.

• As of v1.4.9, you can automatically integrate the Agora RTM Android SDK through Maven Central. To integrate the SDK with Maven Central, see Integrate the SDK.

• As of v1.4.9, you need to add the following permission to the AndroidManifest.xml file of an Android project to check the connection status of the WIFI network:

Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network.

v1.4.7 was released on July 19, 2021.

Improved the success rate of logins and message delivery for the Signaling SDK in poor network conditions.

v1.4.6 was released on June 21, 2021.

Fixed some issues that may cause crashes to improve stability.

v1.4.5 was released on April 30, 2021.

Fixed some issues that may cause crashes to improve stability.

v1.4.4 was released on April 20, 2021.

Integration changes

Because JCenter is about to retire, as of this release, Agora publishes the SDK package to JitPack instead of JCenter. To integrate the SDK with JitPack, see Integrate the SDK.

Improved the success rate of logins and message delivery for the Signaling SDK in poor network conditions.

Fixed some issues that might cause the system to crash.

v1.4.3 was released on February 10, 2021.

This release fixed the following issues:

• Crash issues caused by occasional multi-thread access conflict.

• High timeout rate for RTM login operations.

v1.4.2 was released on November 23, 2020.

Improved performance of login and messaging operations.

v1.4.1 was released on September 30, 2020.

Improved the log file.

v1.4.0 was released on September 1, 2020.

• You need to add new ports to the firewall whitelist. See Firewall Requirements.

  • New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption.

  • New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK’s performance in sub-optimal network conditions.

  • New UDP port: 9700. Reason: Support data reporting.

• In setLogFileSize, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB.

• Geofencing. You can call setRtmServiceContext to set the region of the Agora Signaling SDK. The Signaling SDK can only connect to Agora RTM servers within the specified region.

• Transport encryption. The encryption is enabled by default. To disable the feature, contact support@agora.io.

• Improved the success rate of login and message delivery of the Signaling SDK in poor network conditions.

• Optimized the reconnection mechanism.

New methods

setRtmServiceContext

v1.3.0 was released on May 8, 2020.

• You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See Firewall Requirements.

• The Agora server blocks any file message or image message that you send to RTM SDK 1.2.2 or earlier, or to the Signaling SDK.

1. Send and receive file messages

   v1.3.0 supports downloading non-empty files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each file you upload to the Agora server corresponds to a media ID. The file stays on the Agora server for seven days. You can use the media ID to download the file as long as the file is still on the Agora server.

   v1.3.0 adds the RtmFileMessage message class for saving and transferring a media ID. The RtmFileMessage class inherits from the RtmMessage class, so you can use the existing peer-to-peer or channel messaging methods to transfer the RtmFileMessage instance. You can use the RtmFileMessage object to complete the following tasks:

   • Set the filename and thumbnail of the uploaded file.

   • Get the size of the uploaded file.

2. Send and receive image messages

   v1.3.0 supports downloading non-empty image files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each image you upload to the Agora server corresponds to a media ID. The image file stays in the Agora server for seven days. You can use the media ID to download the image file as long as it is still on the Agora server.

   v1.3.0 adds the RtmImageMessage message class for saving and transferring a media ID. The RtmImageMessage class inherits from the RtmMessage class, so you can use the existing peer-to-peer or channel messaging methods to transfer the RtmImageMessage instance. You can use the RtmImageMessage object to complete the following tasks:

   • Set the filename and thumbnail of the uploaded image file.

   • Get the size of the uploaded image file.

   • Get the SDK-calculated width or height of image files in JPEG, JPG, BMP, or PNG format.

   • Set the width or height of image files. The width or height you set overwrites the width or height that the SDK calculates.

3. Report the progress of upload or download

   The SDK returns the progress of an upload or download by callback every second during a task in progress. If the upload or download task pauses, the SDK ceases to return any further callback until the task continues.

• Login failure caused by the SDK’s incorrect identification of user’s network type.

• Other problems that may cause the system to crash.

New methods

• createFileMessageByMediaId
• createImageMessageByMediaId
• createFileMessageByUploading
• createImageMessageByUploading
• downloadMediaToMemory
• downloadMediaToFile
• cancelMediaUpload
• cancelMediaDownload

New callbacks

• onImageMessageReceived
• onFileMessageReceived
• onImageMessageReceivedFromPeer
• onFileMessageReceivedFromPeer
• onMediaUploadingProgress
• onMediaDownloadingProgress

Deprecated methods

• sendMessage (RtmMessage message, ResultCallback<Void> resultCallback) is deprecated. Use sendMessage (RtmMessage message instead.

v1.2.2 was released on December 13, 2019.

Issues Fixed

Occasionally fails to receive any callback after a channel attribute operation.

v1.2.1 was released on November 29, 2019.

New Feature

Compatible with the endCall method of the Agora Signaling SDK

If you use the sendMessageToPeer method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_<channelId><your additional information>, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace <channelId> with the channel ID from which you want to leave (end call), and replace <your additional information> with any additional information. Note that you must not put any "" (underscore) in your additional information but you can set <your additional information> as empty "".

Issues Fixed

• The SDK fails to reconnect to the Agora RTM system if the user disables VPN.

• If a channel member reconnects to the Agora RTM server after being interrupted, chances are the rest members of the channel can receive onMemberJoined twice.

v1.2.0 was released on November 6, 2019.

New Features

When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed. If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server.

Allows you to unsubscribe from the online status of the specified user(s).

Allows you to get a list of the peers, to whose specific status you have subscribed.

Creates and initializes a raw message to be sent.

If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB.

Issues Fixed

• The system returns rtm native not ready, if one creates multiple channels with the same channelId and then calls join or leave.

v1.1.0 is released on September 18, 2019. It adds the following features:

• Gets the member count of specified channel(s).

• Automatically returns the latest numer of members in the current channel

• Channel attribute operations

Compatibility Changes

1. Deprecates the sendMessageToPeer method, and uses sendMessageToPeer(const char *, const IMessage *, const SendMessageOptions &) instead.

2. The getServerReceivedTs method of the RtmMessage object supports both peer-to-peer and channel messages.

3. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_TIMEOUT.

4. Puts a limit on the frequency of join the same channel: Two times every five seconds.

New Features

1. Gets the member count of specified channel(s).

   You can now get the member count of specified channel(s) without the need to join, by calling the getChannelMemberCount method. You can get the member counts of a maximum of 32 channels in one method call.

2. Automatically returns the latest numer of members in the current channel

   If you are already in a channel, you do not have to call the getChannelMemberCount method to get the member count of the current channel. We also do not recommend using onMemberJoined and onMemberLeft to keep track of the member counts. As of this release, the SDK returns to the channel members onMemberCountUpdated the latest channel member count when the number of channel members changes. Note that:

   • When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second.

   • When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds.

     Please treat this callback and the getMembers method separately:

     • The former is an active callback. It returns the current numer of channel members;

     • The latter relies on the onSuccess callback to return a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly-selected channel members.

3. Channel attribute operations

   Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement.

   Each channel attribute comes as a key-value pair. See RtmChannelAttribute for more information. Where:

   • The key of each channel attribute must be visible characters and not exceed 8 KB.

   • Each channel attribute must not exceed 8 KB in length.

   • The overall size of the attributes of a channel must not exceed 32 KB.

   • The number of attributes of a channel must not exceed 32.

     Specific features:

     • Sets the attributes of a specified channel with new ones.

     • Adds or updates the attribute(s) of a specified channel.

     • Deletes the attributes of a specified channel by attribute keys.

     • Clears all attributes of a specified channel.

     • Gets all attributes of a specified channel.

     • Gets the attributes of a specified channel by attribute keys.

       When updating attributes of a channel, you can use the setEnableNotificationToChannelMembers flag to decide whether or not to notify all members of the channel about this attribute change.

       The SDK caches the channel attributes. If multiple users have the privilege to update the channel attributes, then we recommend calling the getChannelAttributes to update the cache before updating the channel attributes.

Improvements

This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions.

The Agora RTM system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions.

API Changes

• setChannelAttributes: Sets the attributes of a specified channel with new ones.

• addOrUpdaeChannelAttributes: Adds or updates the attribute(s) of a specified channel.

• deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys.

• clearChannelAttributes: Clears all attributes of a specified channel.

• getChannelAttributes: Gets all attributes of a specified channel.

• getChannelAttributesByKeys : Gets the attributes of a specified channel by attribute keys.

• getChannelMemberCount : Gets the member count of specified channel(s).

• onAttributesUpdated: Returns all attributes of the channel when the channel attributes are updated.

• onMemberCountUpdated : Occurs when the number of the channel members changes, and returns the new number.

• GetChannelMemberCountErrCode : Error codes related to retrieving the channel member count of specified channel(s).

• JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN : The frequency of joining the same channel exceeds two times every five seconds.

• sendMessageToPeer: Replaced by the sendMessageToPeer(const char *, const IMessage *, const SendMessageOptions &) method.

• ATTRIBUTE_OPERATION_ERR_NOT_READY: Replaced by ATTRIBUTE_OPERATION_ERR_USER_NOT_LOGGED_IN.

v1.0.1 is released on August 1st, 2019.

Issues Fixed

• When the connection to the Agora RTM system is interrupted, the SDK does not return the onConnectionStateChanged callback.

v1.0.0 is released on July 24th, 2019.

New Features

v1.0.0 implements the LocalInvitation.setChannelId and LocalInvitation.getChannelId methods.

• To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora RTM SDK does not join the channel of the specified channel ID.

• If your App does not involve the legacy Agora Signaling SDK, we recommend using the LocalInvitation.setContent method or the RemoteInvitation.setResponse method to set customized contents.

Supports changing the default path to the SDK log file using the setLogFile method. To avoid creating an incomplete log file, we recommend calling this method once you have created and initialized an RtmClient instance.

Supports setting the output log level of the SDK using the setLogFilter method. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

You can call this method once you have created and initializd an RtmClient instance. You do not have to call this method after calling the login method.

Supports setting the log file size using the setLogFileSize method. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect.

You can call this method once you have created and initializd an RtmClient instance. You do not have to call this method after calling the login method.

Improvements

Adds error codes based on the following scenarios:

• The Agora RTM service is not initialized.

• The method call frequency exceeds the limit.

• The user does not call the login method or the method call of login does not succeed before calling any of the RTM core APIs.

Issues Fixed

• One can log in the Agora RTM system with a static App ID and an RTM token, which is generated from a dynamic App ID.

API Changes

• setLogFile: Specifies the default path to the SDK log file.

• setLogFilter: Sets the output log level of the SDK.

• setLogFileSize: Sets the log file size in KB.

• getSdkVersion : Gets the SDK version.

v0.9.3 was released on June 7th, 2019.

New Features

This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the RTM server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one.

This version allows you to set or update a user’s attributes. You can:

• Substitutes the local user’s attributes with new ones.

• Adds or updates the local user’s attribute(s).

• Deletes the local user’s attributes using attribute keys.

• Clears all attributes of the local user.

• Gets all attributes of a specified user.

• Gets the attributes of a specified user using attribute keys.

Please note that:

• Only after you successfully loggin in the Agora RTM system can you execute user attribute-related operations. Otherwise, the SDK triggers the ATTRIBUTE_OPERATION_ERR_NOT_READY error code.

• The attributes you set will be clears when you log out of Signaling.

• You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW error code.

Improvements

• Supports creating an RTM channel before logging in the Agora RTM system.

• Supports creating multiple RTM channels. But a user can only join a maximum of 20 RTM channels at the same time. When the number of the joined channels exceeds 20, the SDK triggers the JOIN_CHANNEL_ERR_FAILURE error code.

Issues Fixed

• Occasional system crashes.

• A user who has logged out of the Agora RTM system appears online to the other users until 30 seconds later.

v0.9.2 is released on May 5th, 2019.

This release does not support creating an RtmChannel instance before logging in the Agora RTM system

New Features

This release introduces a new concept: online and offline.

• Online: The user has logged in the Agora RTM system.

• Offline: The user has logged out of the Agora RTM system.

This release adds the function of querying the online status of the specified users. After logging in the Agora RTM system, you can get the online status of a maximum of 256 specified users. See queryPeersOnlineStatus.

Please note that:

• The sequence of the returned user IDs is identical to the input sequence.

• The call frequency of this method is 10 times every five seconds.

In the production environment, you need to use a token to log in the Agora RTM system. Each token expires 24 hours after it is created. This release allows you to renew a token.

• If you are logging in the Agora RTM system and if your token has expired, the SDK returns the LOGIN_ERR_TOKEN_EXPIRED error code.

• if you are logged in the Agora RTM system, you will not be kicked out immediately when your token expires. But you need to renew your token the next time you log in the Agora RTM system. Therefore, we still recommend that you renew your token when you receive the onTokenExpired callback.

Please note that:

• The renewToken method must be called before creating an RtmClient.

• The call frequency of the renewToken method is two times every second.

Improvements

• Supports a userId that starts with a space.

API Changes

• Method: queryPeersOnlineStatus

• Error Code: QueryPeersOnlineStatusError

• Method: renewToken

• Callback: onTokenExpired

• Error Codes:

• RenewTokenError

Adds the following error code for when a user sends a call invitation without logging in the Agora RTM system.

• LOCAL_INVITATION_ERR_NOT_LOGGEDIN

v0.9.1 is released on April 4th, 2019.

Please note that this version does not come with the setLogFile and setLogFilter method. The default log file location is at /sdcard/<AppName>/agorartm.log.

New Features

This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call.

Improvements

• Optimizes the object relations to facilitate understanding.

• Renames some interfaces to conform to Java naming conventions.

• Removes ChannelMessageState and PeerMessageState to simplify the process of sending a channel or peer-to-peer message. Uses ChannelMessageError and PeerMessageError instead.

• Removes IStateListener for listening to message states. Uses the generic ResultCallback instead.

API Changes

• LocalInvitation.setContent(): allows the caller to set the content of an outgoing call invitation.

• LocalInvitation.getContent(): allows the caller to retrieve the content of an outgoing call invitation.

• LocalInvitation.getResponse(): allows the caller to retrieve the response set by the callee.

• LocalInvitation.getState(): allows the caller to retrieve the state of an outgoing call invitation.

• RemoteInvitation.getCallerId() : allows the callee to retrieve the user ID of the caller.

• RemoteInvitation.getContent() : allows the callee to retrieve the content set by the caller.

• RemoteInvitation.setResponse(): allows the callee to set the response to the caller.

• RemoteInvitation.getResponse(): allows the callee to retrieve the response to the caller.

• RemoteInvitation.getState(): allows the callee to retrieve the state of the incoming call invitation

• RtmCallEventListener.onLocalInvitationReceivedByPeer(): occurs when the callee receives the call invitation.

• RtmCallEventListener.onLocalInvitationAccepted(): occurs when the callee accepts the call invitation.

• RtmCallEventListener.onLocalInvitationRefused(): occurs when the callee declines the call invitation.

• RtmCallEventListener.onLocalInvitationCanceled(): occurs when the caller cancels the call invitation.

• RtmCallEventListener.onLocalInvitationFailure(): occurs when the outgoing call invitation fails.

• RtmCallEventListener.onRemoteInvitationReceived(): occurs when the callee receives a call invitation.

• RtmCallEventListener.onRemoteInvitationAccepted(): occurs when the callee accepts a call invitation.

• RtmCallEventListener.onRemoteInvitationRefused(): occurs when the callee declines a call invitation.

• RtmCallEventListener.onRemoteInvitationCanceled(): occurs when the caller cancels the call invitation.

• RtmCallEventListener.onRemoteInvitationFailure(): occurs when the incoming call invitation fails.

• RtmCallManager.setEventListener(): sets the event listener to the RtmCallManager instance.

• RtmCallManager.createLocalInvitation(): creates a call invitation.

• RtmCallManager.sendLocalInvitation(): sends a call invitation to a specified user.

• RtmCallManager.acceptRemoteInvitation() : accepts an incoming call invitation.

• RtmCallManager.refuseRemoteInvitation(): declines an incoming call invitation.

• RtmCallManager.cancelLocalInvitation(): allows the caller to cancel an outgoing call invitation.

• RtmStatusCode#LocalInvitationState: states of an outgoing call invitation.

• RtmStatusCode#RemoteInvitationState : states of an incoming call invitation.

• RtmStatusCode#LocalInvitationError: error codes of an outgoing call invitation.

• RtmStatusCode#RemoteInvitationError: error codes of an incoming call invitation.

• RtmStatusCode#InvitationApiCallError: error codes of the invitation-specific API calls.

• ConnectionChangeReason#CONNECTION_CHANGE_REASON_REMOTE_LOGIN: another instance has logged in the Agora RTM system with the same user ID.

• The RtmClient.destroy() method, which releases all resources used by the RtmClient instance, to: RtmClient.release().

• The IResultCallback class to: ResultCallback

• Deletes PEER_MESSAGE_RECEIVED_BY_SERVER from PeerMessageError, uses PEER_MESSAGE_ERR_OK instead.

• Deletes CHANNEL_MESSAGE_RECEIVED_BY_SERVER from ChannelMessageError, uses CHANNEL_MESSAGE_OK instead.

• Deletes the PeerMessageState interface, uses PeerMessageError instead.

• Deletes the ChannelMessageState interface, uses ChannelMessageError instead.

• Deletes the IStateListener class for listening to message states, uses the ResultCallback class instead for listening to the peer or channel message results.

• Success: the SDK returns the ResultCallback.onSuccess() callback.

• Failure: the SDK returns the ResultCallback.onFailure() callback with the corresponding error codes.

v0.9.0 is released on February 4th, 2019.

Initial version.

Key features:

• Sends or receives peer-to-peer messages.

• Joins or leaves a channel.

• Sends or receives channel messages.

This page contains information on the following releases: