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

Login and logout
Sending a peer-to-peer message
Querying the online status of specified users
Subscribing to or unsubscribing from the online status of specified users
User attribute operations
Channel attribute operations
Retrieving channel member count of specified channels
Joining and leaving a Channel
Sending a channel message
Retrieving a member list of the current channel
Call invitation
Renewing the current RTM Token
Logfile settings and version check
Customized method
Geofencing and cloud proxy

Login and logout

‍You need to understand the connection state between the SDK and the Agora RTM system before developing an RTM app. For more information, see Manage Connection States.

Method	Description
createRtmService	Creates and returns `IRtmService` instance.
initialize	Initializes `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.

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 online peer-to-peer message to a specified user (receiver). When used with a prefix, this method is similar to the `endCall` method of the Agora Signaling SDK.
release	Releases all resources that the `IMessage` uses.

Event	Description
onSendMessageResult	Returns the result of the `sendMessageToPeer` or `sendMessageToPeer(const char peerId, const IMessage message, const SendMessageOptions &options)` 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 users

Method	Description
subscribePeersOnlineStatus	Subscribes to the online status of the specified users.
unsubscribePeersOnlineStatus	Unsubscribes from the online status of the specified users.
queryPeersBySubscriptionOption	Gets a list of the peers, to whose specific status you have subscribed.

Event	Description
onSubscriptionRequestResult	Reports the result of the `subscribePeersOnlineStatus` or the `unsubscribePeersOnlineStatus` method call.
onPeersOnlineStatusChanged	Occurs when the online status of the peers, to whom you subscribe, changes. See `PeerOnlineStatus` for the online status of a peer.
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 attributes.
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	Reports the result of the `setLocalUserAttributes` method call.
onAddOrUpdateLocalUserAttributesResult	Reports the result of the `addOrUpdateLocalUserAttributes` method call.
onDeleteLocalUserAttributesResult	Reports the result of the `deleteLocalUserAttributesByKeys` method call.
onClearLocalUserAttributesResult	Reports the result of the `clearLocalUserAttributes` method call.
onGetUserAttributesResult	Reports 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 attributes 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	Reports the result of the `setChannelAttributes` method call.
onAddOrUpdateChannelAttributesResult	Reports the result of the `addOrUpdateChannelAttributes` method call.
onDeleteChannelAttributesResult	Reports the result of the `deleteChannelAttributesByKeys` method call.
onClearChannelAttributesResult	Reports the result of the `clearChannelAttributes` method call.
onGetChannelAttributesResult	Reports the result of the `getChannelAttributes` or `getChannelAttributesByKeys` method call.

Event for all channel members	Description
onAttributesUpdated	Reports all attributes of the channel when the channel attributes are updated.

Retrieving channel member count of specified channels

Method	Description
getChannelMemberCount	Gets the member count of specified channels. You do not have to join the specified channels to call this method.

Event	Description
onGetChannelMemberCountResult	Reports 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	Reports 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. This callback 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.
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	Reports 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	Reports the result of the `getMembers` method call. For the data structure of the channel member, see `IChannelMember`.

Managing call invitation

API calling sequence for canceling a sent call invitation:

API calling sequence for accepting a received call invitation:

API calling sequence for 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.
cancelLocalInvitation	Allows the caller to cancel a call invitation.
release	Releases all resources used by the `ILocalCallInvitation` instance.

Callee Method	Description
acceptRemoteInvitation	Allows the callee to accept a call invitation.
refuseRemoteInvitation	Allows the callee to decline a call invitation.
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.

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.

Renew the Token

Method	Description
renewToken	Renews the RTM Token of the SDK.

Event	Description
onTokenExpired	Occurs when the RTM server detects that the RTM token has exceeded the specified validity period.
onRenewTokenResult	Reports the result of the `renewToken` method call.

Log file settings and version check

‍- You can perform log file related operations 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 IRtmService 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 size of a single log file. The SDK has two log files with the same size.
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.

Geofencing and cloud proxy

Method	Description
setRtmServiceContext	Sets the context of all `IRtmservice` instances. All `IRtmservice` instances you create after calling this method match the context.