Overview

Designed as a replacement for the legacy Agora Signaling SDK, the Agora Real-time Messaging (RTM) SDK provides a more streamlined and stable messaging mechanism for you to quickly implement real-time messaging under various scenarios.

For more information about the features and applications of the Agora RTM SDK, see Product Overview.

v1.2.2

v1.2.2 was released on December 12, 2019.

Issues Fixed

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

v1.2.1

v1.2.1 was released on November 20, 2019.

New Feature

Compatible with the endCall method of the Agora Signaling SDK

If you use the sendMessageToPeer method to send off a text message that starts off with AGORA_RTM_ENDCALL_PREFIX_<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

v1.2.0 was released on November 6, 2019.

New Features

Subscribe to the online status of the specified user(s)

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.

Unsubscribe from the online status of the specified user(s)

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

Get a list of the peers, to whose specific status you have subscribed

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

Create a raw message

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

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

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

Resends peer-to-peer messages

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.

Caches channel messages

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

Added Methods

Added Callbacks

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

Added Error Codes

Deprecated Methods

Deprecated Error Codes

v1.0.1

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

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

New Features

Interconnects with the legacy Agora Signaling SDK

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.

Specifies the default path to the SDK log file

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.

Sets the output log level of the SDK

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.

Sets the log file size in KB

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

v0.9.3

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

New Features

Sends an (offline) peer-to-peer message to a specified user (receiver)

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.
  • 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 the RTM system.
  • 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

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

Queries the Online Status of the Specified Users

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.

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

Renews the Token

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.

Improvements

  • Supports a userId that starts with a space.

API Changes

Queries the Online Status of the Specified Users

Adds

Renews the Token

Adds

Call Invitation

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

v0.9.1

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

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

Adds

Renames

Deletes

v0.9.0

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.