Agora RTM Web API Reference

The Agora RTM Web SDK is a JavaScript library loaded by an HTML web page. The Agora RTM Web SDK library uses APIs in the web browser to establish real-time messaging services.

AgoraRTM is the exported module of the Agora RTM SDK. If you import the Agora RTM Web SDK using the <script> tag, the SDK creates a global variable called AgoraRTM, which includes all the module members.

Please use the RtmClient.on and RtmChannel.on methods to add event listeners to the RtmClient and RtmChannel objects.

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 the 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 or leaving a channel
• Channel message
• Retrieving a member list of the channel
• Call invitation management
• Renewing the Token
• Log settings and version check
• Client instance settings

Login and logout

Method	Description
createInstance	Creates an RtmClient instance.
login	Logs in to the Agora RTM system.
logout	Logs out of the Agora RTM system.

Event	Description
ConnectionStateChanged	Occurs when the connection state between the SDK and the Agora RTM system changes.

Sending a peer-to-peer message

Method	Description
sendMessageToPeer	Sends a peer-to-peer message to a specified user.

Event	Description
MessageFromPeer	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.

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
PeersOnlineStatusChanged	Occurs when the online status of the peers, to whom you subscribe, changes.

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
PeersOnlineStatusChanged	Occurs when the online status of the peers, to whom you subscribe, changes.

User attribute operations

Method	Description
setLocalUserAttributes	Resets the local user's attributes.
addOrUpdateLocalUserAttributes	Adds or updates the local user's attributes.
deleteLocalUserAttributesByKeys	Deletes the local user's attributes using 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.

Channel attribute operations

Method	Description
setChannelAttributes	Resets the attributes of a specified channel.
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 for all channel members	Description
AttributesUpdated	Occurs when the channel attributes are updated, and returns all attributes of the channel.

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.

Joining or leaving a channel

Method	Description
createChannel	Creates an RtmChannel instance.
join	Joins the channel.
leave	Leaves the channel.

Event	Description
MemberJoined	Occurs when a remote user joins the channel.
MemberLeft	Occurs when a remote member leaves the channel.
MemberCountUpdated	Occurs when the number of the channel members changes, and returns the new number.

Channel message

Method	Description
sendMessage	Allows a channel member to send a message to all members in the channel.

Event	Description
ChannelMessage	Occurs when the local user receives a channel message.

Retrieving a member list of the channel

Method	Description
getMembers	Retrieves a member list of the current channel.

Call invitation management

• 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:、

Caller Method	Description
createLocalInvitation	Allows the caller to create a LocalInvitation instance.
send	Allows the caller to send a call invitation to a remote user.
cancel	Allows the caller to cancel a call invitation.

Callee Method	Description
accept	Allows the callee to accept a call invitation.
refuse	Allows the callee to refuse a call invitation.

Caller Event	Description
LocalInvitationReceivedByPeer	Callback to the caller: occurs when the callee receives the call invitation.
LocalInvitationCanceled	Callback to the caller: occurs when the caller cancels an outgoing call invitation.
LocalInvitationAccepted	Callback to the caller: occurs when the callee accepts the call invitation.
LocalInvitationRefused	Callback to the caller: occurs when the callee declines the call invitation.
LocalInvitationFailure	Callback to the caller: occurs when the life cycle of an outgoing call invitation ends in failure.

Callee Event	Description
RemoteInvitationReceived	Callback to the callee: occurs when the callee receives a call invitation.
RemoteInvitationCanceled	Callback to the callee: occurs when the callee receives a call invitation.
RemoteInvitationAccepted	Callback to the callee: occurs when the callee accepts a call invitation.
RemoteInvitationRefused	Callback to the callee: occurs when the callee declines a call invitation.
RemoteInvitationFailure	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 current token.

Event	Description
TokenExpired	Occurs when the token expires.

Log settings and version check

Variable	Description
enableLogUpload	Determines whether to enable log upload.
logFilter	Sets the output log level of the SDK.
VERSION	Version of the Agora RTM SDK.

Client instance settings

Method	Description
updateConfig	Modifies the RtmClient instance configuration. The changes take effect immediately.