The Agora RTM SDK provides a stable messaging mechanism for you to implement real-time messaging scenarios.

This page lists the core APIs of the Agora RTM SDK. Unless otherwise specified, most of the core APIs should only be called after the login method call succeeds and after you receive the onLoginSuccess callback.

Following are the core functionalities that the Agora RTM SDK.

Login & Logout

The connection state between the SDK and the Agora RTM system is a core concept for you to understand before developing an RTM app. For more information, see Manage Connection States.

Method Description
createAgoraService Creates and returns an IAgoraService instance.
initialize Initializes an IAgoraService instance.
createRtmService Creates and returns an IRtmService instance.
initialize Initializes an IRtmService instance.
login Logs in the Agora RTM system.
logout Logs out of the Agora RTM system.
release Releases all resources that the IRtmService instance uses.
release Releases all resources that the IAgoraService instance uses.
Event Description
onLoginSuccess Occurs when a user logs in the Agora RTM system.
onLoginFailure Occurs when a user fails to log in the Agora RTM system.
onLogout Occurs when a user logs out of the Agora RTM system.
onConnectionStateChanged Occurs when the connection state between the SDK and the Agora RTM system changes.

Sending a peer-to-peer message

Method Description
createMessage Creates and returns an empty text IMessage instance.
createMessage Creates and returns a text IMessage instance.
createMessage Creates and returns a raw IMessage instance.
createMessage Creates and returns a raw IMessage instance and sets its description.
sendMessageToPeer Sends an (offline) peer-to-peer message to a specified user (receiver). When used with a prefix, it serves a similar function to the endCall method of the Agora Signaling SDK. For information about offline messaging settings, see enableOfflineMessaging.
release Releases all resources that the IMessage uses.
Event Description
onSendMessageResult Returns the result of the sendMessageToPeer or sendMessageToPeer method call.
onMessageReceivedFromPeer Occurs when receiving a peer-to-peer message.

Querying the online status of the specified users

Method Description
queryPeersOnlineStatus Queries the online status of the specified users.
Event Description
onQueryPeersOnlineStatusResult Returns the result of the queryPeersOnlineStatus method call.

Subscribing to or unsubscribing from the online status of specified user(s)

Method Description
subscribePeersOnlineStatus Subscribes to the online status of the specified user(s)
unsubscribePeersOnlineStatus Unsubscribes from the online status of the specified user(s).
queryPeersBySubscriptionOption Gets a list of the peers, to whose specific status you have subscribed. See PEER_SUBSCRIPTION_OPTION for the status type, to which you have subscribed.
Event Description
onSubscriptionRequestResult Returns the result of the subscribePeersOnlineStatus or unsubscribePeersOnlineStatus method call.
onPeersOnlineStatusChanged Occurs when the online status of the peers, to whom you subscribe, changes.
onQueryPeersBySubscriptionOptionResult Returns the result of the queryPeersBySubscriptionOption method call.

User attribute operations

Method Description
createChannelAttribute Creates and returns an IRtmChannelAttribute instance.
setLocalUserAttributes Substitutes the local user's attributes with new ones.
addOrUpdateLocalUserAttributes Adds or updates the local user's attribute(s).
deleteLocalUserAttributesByKeys Deletes the local user's attributes by attribute keys.
clearLocalUserAttributes Clears all attributes of the local user.
getUserAttributes Gets all attributes of a specified user.
getUserAttributesByKeys Gets the attributes of a specified user by attribute keys.
Event Description
onSetLocalUserAttributesResult Returns the result of the setLocalUserAttributes method call.
onAddOrUpdateLocalUserAttributesResult Returns the result of the addOrUpdateLocalUserAttributes method call.
onDeleteLocalUserAttributesResult Returns the result of the deleteLocalUserAttributesByKeys method call.
onClearLocalUserAttributesResult Returns the result of the clearLocalUserAttributes method call.
onGetUserAttributesResult Returns the result of the getUserAttributes or getUserAttributesByKeys method call.

Channel attribute operations

Method Description
setChannelAttributes Sets the attributes of a specified channel with new ones.
addOrUpdateChannelAttributes 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.
Event Description
onSetChannelAttributesResult Returns the result of the setChannelAttributes method call.
onAddOrUpdateChannelAttributesResult Returns the result of the addOrUpdateChannelAttributes method call.
onDeleteChannelAttributesResult Returns the result of the deleteChannelAttributesByKeys method call.
onClearChannelAttributesResult Returns the result of the clearChannelAttributes method call.
onGetChannelAttributesResult Returns the result of the getChannelAttributes or getChannelAttributesByKeys method call.
Event for all channel members Description
onAttributesUpdated Returns all attributes of the channel when the channel attributes are updated. See enableNotificationToChannelMembers for how to enable it.

Retrieving channel member count of specified channel(s)

Method Description
getChannelMemberCount Gets the member count of specified channel(s).
Event Description
onGetChannelMemberCountResult Returns the result of the getChannelMemberCount method call.

Joining or leaving a channel

Method Description
createChannel Creates an IChannel object.
join Joins a channel.
leave Leaves a channel.
release Releases all resources used by the IChannel object.
Event Description
onJoinSuccess Occurs when a user joins a channel.
onJoinFailure Occurs when a user fails to join a channel.
onLeave Returns the result of the leave method call.
onMemberJoined Occurs when a user joins a channel.
onMemberLeft Occurs when a channel member leaves a channel.
onMemberCountUpdated Occurs when the number of the channel members changes, and returns the new number.

Channel message

Method Description
createMessage Creates and returns an empty text IMessage instance.
createMessage Creates and returns an text IMessage instance.
createMessage Creates and returns an raw IMessage instance.
createMessage Creates and returns an IMessage instance and sets its description.
sendMessage Allows a channel member to send a message to all members the channel.
release Releases all resources that the IMessage uses.
Event Description
onSendMessageResult Returns the result of the sendMessage method call.
onMessageReceived Occurs when all remote users receive a channel message from a sender.

Retrieving a member list of the channel

Method Description
getMembers Retrieves the member list of a channel.
Event Description
onGetMembers Returns the result of the getMembers method call. For the data structure of the channel member, see IChannelMember.

Call invitation management

  • API calling sequence for canceling a sent call invitation:
  • API calling sequence for accepting or declining a received call invitation:
Method for Managing a Call Manager Description
getRtmCallManager Gets an RTM call manager.
release Releases all resources used by the IRtmCallManager instance.
Caller Method Description
createLocalCallInvitation Allows the caller to create and manage an ILocalCallInvitation object.
sendLocalInvitation Allows the caller to send a call invitation to a remote user. See INVITATION_API_CALL_ERR_CODE for the error code.
cancelLocalInvitation Allows the caller to cancel a call invitation. See INVITATION_API_CALL_ERR_CODE for the error code.
release Releases all resources used by the ILocalCallInvitation instance.
Callee Method Description
acceptRemoteInvitation Allows the callee to accept a call invitation. See INVITATION_API_CALL_ERR_CODE for the error code.
refuseRemoteInvitation Allows the callee to decline a call invitation. See INVITATION_API_CALL_ERR_CODE for the error code.
release Releases all resources used by the IRemoteCallInvitation instance.
Caller Event Description
onLocalInvitationReceivedByPeer Callback to the caller: occurs when the callee receives the call invitation.
onLocalInvitationCanceled Callback to the caller: occurs when the caller cancels a sent call invitation.
onLocalInvitationAccepted Callback to the caller: occurs when the callee accepts the call invitation.
onLocalInvitationRefused Callback to the caller: occurs when the callee refuses the call invitation.
onLocalInvitationFailure Callback to the caller: occurs when the life cycle of an outgoing call invitation ends in failure. See LOCAL_INVITATION_ERR_CODE for the error code.
Callee Event Description
onRemoteInvitationReceived Callback to the callee: occurs when the callee receives a call invitation. At the same time, the SDK returns an IRemoteCallInvitation object to the callee.
onRemoteInvitationAccepted Callback to the callee: occurs when the callee accepts a call invitation.
onRemoteInvitationRefused Callback to the callee: occurs when the callee declines a call invitation.
onRemoteInvitationCanceled Callback to the callee: occurs when the caller cancels the call invitation.
onRemoteInvitationFailure Callback to the callee: occurs when the life cycle of the incoming call invitation ends in failure. See REMOTE_INVITATION_ERR_CODE for the error code.

Renew the Token

Method Description
renewToken Renews the current RTM Token.
Event Description
onTokenExpired Occurs when the current RTM Token exceeds the 24-hour validity period.
onRenewTokenResult Returns the result of the renewToken method call.

Logfile settings & Version check

  • Logfile-related operations can be done after creating and initializing the IRtmService instance and before calling the login method.
  • getRtmSdkVersion is a global method. You can call it before creating and initializing an IAgoraService instance.
Method Description
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 (KB).
getRtmSdkVersion Gets the version of the Agora RTM SDK.

Customized method

Method Description
setParameters Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.