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.

Login & Logout

Method Description
createInstance Creates an RtmClient instance.
  • See CreateInstanceError for the error codes.
  • login Logs in the Agora RTM system.
  • See LoginError for the error codes.
  • logout Logs out of the Agora RTM system.
  • See LogoutError for the error codes.
  • 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 an (offline) peer-to-peer message to a specified user.
  • See PeerMessageError for the error codes.
  • 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.
  • Promise<object> returns the result of this method call.
  • See QueryPeersOnlineStatusError for the error codes.
  • 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).
  • See PeerSubscriptionStatusError for the error codes.
  • unsubscribePeersOnlineStatus Unsubscribes from the online status of the specified user(s).
  • See PeerSubscriptionStatusError for the error codes.
  • queryPeersBySubscriptionOption Gets a list of the peers, to whose specific status you have subscribed.
  • See QueryPeersBySubscriptionOptionError for the error codes..
  • See PeerSubscriptionOption for the subscription option type.
  • Event Description
    PeersOnlineStatusChanged Occurs when the online status of the peers, to whom you subscribe, changes.

    User attribute operations

    Method Description
    setLocalUserAttributes Substitutes the local user's attributes with new ones.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • addOrUpdateLocalUserAttributes Adds or updates the local user's attribute(s).
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • deleteLocalUserAttributesByKeys Deletes the local user's attributes using attribute keys.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • clearLocalUserAttributes Clears all attributes of the local user.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • getUserAttributes Gets all attributes of a specified user.
  • Promise<object> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • getUserAttributesByKeys Gets the attributes of a specified user by attribute keys.
  • Promise<object> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • Channel attribute operations

    Method Description
    setChannelAttributes Substitutes the attributes of a specified channel with new ones.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • addOrUpdateChannelAttributes Adds or updates the attribute(s) of a specified channel.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • deleteChannelAttributesByKeys Deletes the attributes of a specified channel by attribute keys.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • clearChannelAttributes Clears all attributes of a specified channel.
  • Promise<void> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • getChannelAttributes Gets all attributes of a specified channel.
  • Promise<object> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • getChannelAttributesByKeys Gets the attributes of a specified channel by attribute keys.
  • Promise<object> returns the result of this method call.
  • See AttributeOperationError for the error codes.
  • 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 channel(s)

    Method Description
    getChannelMemberCount Gets the member count of specified channel(s).
  • Promise<object> returns the result of this method call.
  • See GetChannelMemberCountErrCode for the error codes.
  • Joining or leaving a channel

    Method Description
    createChannel Creates an RtmChannel instance.
  • See CreateChannelError for the error codes.
  • join Joins the channel.
  • Promise<void> returns the result of this method call.
  • See JoinChannelError for the error codes.
  • leave Leaves the channel.
  • Promise<void> returns the result of this method call.
  • See LeaveChannelError for the error codes.
  • 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.
  • Promise<void> returns the result of this method call.
  • See ChannelMessageError for the error codes.
  • 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 channel.
  • Promise<string[]> returns the result of this method call.
  • See GetMembersError for the error codes.
  • Call invitation management

    Caller Method Description
    createLocalInvitation Allows the caller to create a LocalInvitation instance.
  • See InvitationApiCallError for the error codes.
  • send Allows the caller to send a call invitation to a remote user.
  • See InvitationApiCallError for the error codes.
  • cancel Allows the caller to cancel a call invitation.
  • See InvitationApiCallError for the error codes.
  • Callee Method Description
    accept Allows the callee to accept a call invitation.
  • See InvitationApiCallError for the error codes.
  • refuse Allows the callee to refuse a call invitation.
  • See InvitationApiCallError for the error codes.
  • 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.
  • See LocalInvitationFailureReason for the error codes.
  • Callee Event Description
    RemoteInvitationReceived Callback to the callee: occurs when the callee receives a call invitation. At the same time, the SDK returns a RemoteInvitation object to the callee.
    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.
  • See RemoteInvitationFailureReason for the error codes.
  • Renew the Token

    Method Description
    renewToken Renews the current token.
  • Promise<void> returns the result of this method call.
  • See RenewTokenError for the error codes.
  • Event Description
    TokenExpired Occurs when the token expires.

    Logfile settings & Version check

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

    Customized method

    Method Description
    setParameters Provides the technical preview functionalities or special customizations. See RtmParameters.