Options
All
  • Public
  • Public/Protected
  • All
Menu

Class RtmClient

Class that represents the RTM client. You can call the createInstance method of AgoraRTM to create an RtmClient instance. This class is the entry point of the Agora RTM SDK.

Hierarchy

Index

Methods

addOrUpdateChannelAttributes

  • Adds or updates the attributes of a specified channel.

    This method updates the specified channel's attributes if it finds that the attributes has/have the same keys, or adds attributes to the channel if it does not.

    Note

    Parameters

    Returns Promise<void>

addOrUpdateLocalUserAttributes

  • addOrUpdateLocalUserAttributes(attributes: AttributesMap): Promise<void>
  • Adds or updates the local user's attributes.

    This method updates the local user's attributes if it finds that the attributes has/have the same keys, or adds attributes to the local user if it does not.

    Parameters

    • attributes: AttributesMap

      The attributes to be added or updated.

    Returns Promise<void>

    The Promise resolves after successfully adding or updating the local user's attributes.

clearChannelAttributes

clearLocalUserAttributes

  • clearLocalUserAttributes(): Promise<void>
  • Clears all attributes of the local user.

    Returns Promise<void>

    The Promise resolves after successfully clearing the local user's attributes.

createChannel

  • Creates an RtmChannel instance.

    Parameters

    • channelId: string

      The unique channel name of the Agora RTM channel. The string length must be less than 64 bytes with the following character scope:

      • All lowercase English letters: a to z
      • All uppercase English letters: A to Z
      • All numeric characters: 0 to 9
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

      Note:

      • The channelId cannot be empty, null, or "null".

    Returns RtmChannel

    An RtmChannel instance.

createLocalInvitation

createMediaMessageByUploading

  • deprecated

    Deprecated as of v1.5.1. Agora recommends that you do not use it.

    Uploads a file to the Agora server to get an RtmFileMessage instance for file messages.

    example
    // Blob from a file
    const blob = <Blob>
    // Upload a file to create an RtmFileMessage instance
    const mediaMessage = await client.createMediaMessageByUploading(blob, { messageType: 'FILE' })
    // Send a peer-to-peer file message
    await client.sendMessageToPeer(mediaMessage, <peerId>)

    Parameters

    • payload: Blob

      Content of the file in binary format. Must not exceed 32 MB in size.

    • Optional params: undefined | object

      Contains the name of the file to upload, the description of the file message, the thumbnail, and the message type.

      • fileName string
        Name of the file to upload. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • description string
        Description of the file message. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • thumbnail undefined | Blob
        Thumbnail of the file to upload. Must in binary format. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • messageType ''FILE''
        Message type. ''FILE'' stands for file messages.
    • Optional transHandler: MediaTransferHandler

      A MediaTransferHandler instance. You can use this parameter to cancel an upload or report the upload progress.

    Returns Promise<RtmFileMessage>

    The Promise resolves after the file is successfully uploaded. The value of the Promise is an RtmFileMessage instance for sending channel messages and peer-to-peer messages.

  • Uploads an image to the Agora server to get an RtmImageMessage instance for sending image messages.

    example
    // Blob from an image
    const blob = <Blob>
    // Upload an image to create an RtmImageMessage instance
    const mediaMessage = await client.createMediaMessageByUploading(blob, {
    messageType: 'IMAGE',
    fileName: 'file_name',
    description: 'description',
    thumbnail: blob,
    width: 100,
    height: 200,
    thumbnailWidth: 50,
    thumbnailHeight: 200,
    })
    // Send a peer-to-peer image message
    await client.sendMessageToPeer(mediaMessage, <peerId>)

    Parameters

    • payload: Blob

      Content of the image in binary format. Must not exceed 32 MB in size.

    • Optional params: undefined | object

      Contains the the width, height, name of the image file to upload, the description of the image message, the thumbnail, the width and height of the thumbnail, and the message type.

      • width number
        Width of the image file to upload in pixels. If you do not specify this value and the uploaded file format is JPG, JPEG, BMP, or PNG, the SDK automatically calculates the width. The SDK does not resize or crop the image.
      • height number
        Height of the image file to upload in pixels. If you do not specify this value and the uploaded file format is JPG, JPEG, BMP, or PNG, the SDK automatically calculates the height. The SDK does not resize or crop the image.
      • fileName string
        Name of the image file to upload. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • description string
        Description of the image message. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • thumbnail undefined | Blob
        Thumbnail of the image to upload. Must in binary format. The maximum total size of fileName, description, and thumbnail is 32 KB.
      • thumbnailWidth undefined | number
        Width of the thumbnail in pixels. If you do not specify this value, the SDK automatically calculates the width.
      • thumbnailHeight undefined | number
        Height of the thumbnail in pixels. If you do not specify this value, the SDK automatically calculates the height.
      • messageType ''IMAGE''
        Message type. ''IMAGE'' stands for image messages.
    • Optional transHandler: MediaTransferHandler

      A MediaTransferHandler instance. You can use this parameter to cancel an upload or report the upload progress.

    Returns Promise<RtmImageMessage>

    The Promise resolves after the image file is successfully uploaded. The value of the Promise is an RtmImageMessage instance for sending channel messages and peer-to-peer messages.

createMessage

  • createMessage<T>(message: Partial<T>): T
  • Creates a message instance for sending peer-to-peer or channel messages.

    alert

    As of v1.5.1, this method no longer supports creating file messages and image messages.

    example
    const mediaMessage = client.createMessage({
    mediaId: <mediaId>,
    mediaType: 'FILE',
    }) // Create an RtmFileMessage instance

    Type parameters

    Parameters

    • message: Partial<T>

      An object that includes any property of RtmMessage.

    Returns T

    A message instance to send. You can use the message instance to send peer-to-peer or channel messages.

deleteChannelAttributesByKeys

  • deleteChannelAttributesByKeys(channelId: string, attributeKeys: string[], options?: ChannelAttributeOptions): Promise<void>

deleteLocalUserAttributesByKeys

  • deleteLocalUserAttributesByKeys(attributeKeys: string[]): Promise<void>
  • Deletes the local user's attributes using attribute keys.

    Parameters

    • attributeKeys: string[]

      A list of the attribute keys to be deleted.

    Returns Promise<void>

    The Promise resolves after successfully deleting the local user's attributes.

downloadMedia

  • deprecated

    Deprecated as of v1.5.1. Agora recommends that you do not use it.

    Downloads a file or image file from the Agora server by media ID.

    example
    // Download a file blob
    client.on('MessageFromPeer', async message => {
    if (message.messageType === 'FILE') {
    const blob = await client.downloadMedia(message.mediaId)
    }
    })

    Parameters

    • mediaId: string

      Media ID of the uploaded file or image file. The SDK automatically returns a media ID when a file or image file is successfully uploaded to the Agora server. You can use the RtmFileMessage instance or the RtmImageMessage instance to get the media ID of a file or image file.

    • Optional transHandler: MediaTransferHandler

      A MediaTransferHandler instance. You can use this parameter to cancel a download or report the download progress.

    Returns Promise<Blob>

    The Promise is resolved when the download is complete. The value of the Promise is the Blob instance that represents the downloaded file or image file.

getChannelAttributes

  • Gets all attributes of a specified channel.

    Note

    Parameters

    • channelId: string

      The ID of the specified channel.

    Returns Promise<ChannelAttributes>

getChannelAttributesByKeys

  • getChannelAttributesByKeys(channelId: string, keys: string[]): Promise<ChannelAttributes>
  • Gets the attributes of a specified channel by attribute keys.

    Note

    Parameters

    • channelId: string

      The ID of the specified channel.

    • keys: string[]

      An array of attribute keys.

    Returns Promise<ChannelAttributes>

getChannelMemberCount

  • Gets the member count of specified channels.

    Note

    • The call frequency limit for this method is one call per second.
    • We do not support getting the member counts of more than 32 channels in one method call.

    Parameters

    • channelIds: string[]

      An array of the specified channel IDs.

    Returns Promise<ChannelMemberCountResult>

getUserAttributes

  • Gets all attributes of a specified user.

    Parameters

    • userId: string

      The user ID of the specified user.

    Returns Promise<AttributesMap>

getUserAttributesByKeys

  • getUserAttributesByKeys(userId: string, attributeKeys: string[]): Promise<AttributesMap>
  • Gets the attributes of a specified user by attribute keys.

    Parameters

    • userId: string

      The user ID of the specified user.

    • attributeKeys: string[]

      An array of the attribute keys.

    Returns Promise<AttributesMap>

login

  • login(options: object): Promise<void>
  • Logs in to the Agora RTM system.

    note

    If you use the Agora RTM SDK together with the Agora RTC SDK, Agora recommends that you avoid logging in to the RTM system and joining the RTC channel at the same time.

    note

    If the user logs in with the same uid from a different instance, the user will be kicked out of your previous login and removed from previously joined channels.

    Parameters

    • options: object
      • Optional token?: undefined | string

        An optional token generated by the app server.

      • uid: string

        The uid of the user logging in the Agora RTM system. The string length must be less than 64 bytes with the following character scope:

        • All lowercase English letters: a to z
        • All uppercase English letters: A to Z
        • All numeric characters: 0 to 9
        • The space character.
        • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

        Note

        • The uid cannot be empty, or set as null or "null".
        • We do not support uids of the number type and recommend using the toString() method to convert your non-string uid.

    Returns Promise<void>

    The Promise resolves after the user logs in to the Agora RTM system successfully.

logout

  • logout(): Promise<void>
  • Allows a user to log out of the Agora RTM system.

    After the user logs out of the Agora RTM system, the SDK disconnects from the Agora RTM system and destroys the corresponding event listener.

    Returns Promise<void>

    The Promises resolves after the user logs out of the Agora RTM system and disconnects from WebSocket.

on

  • on<EventName>(eventName: EventName, listener: function): this
  • Adds the listener function to the channel for the event named eventName. See the EventEmitter API documentation for other event methods on the RtmClient instance.

    Type parameters

    • EventName: keyof RtmClientEvents

    Parameters

    • eventName: EventName

      The name of the RTM client event. See the property names in the RtmClientEvents for the list of events.

    • listener: function

      The callback function of the RTM client event.

        • (...args: ListenerType<RtmClientEvents[EventName]>): any
        • Parameters

          • Rest ...args: ListenerType<RtmClientEvents[EventName]>

          Returns any

    Returns this

queryPeersBySubscriptionOption

queryPeersOnlineStatus

  • Queries the online status of the specified users.

    Parameters

    • peerIds: string[]

      A list of the user IDs. The number of user IDs must not exceed 256.

    Returns Promise<PeersOnlineStatusResult>

renewToken

  • renewToken(token: string): Promise<void>
  • Renews the token.

    Parameters

    • token: string

      Your new Token.

    Returns Promise<void>

sendMessageToPeer

  • Allows a user to send an (offline) peer-to-peer message to a specified remote user.

    You can send messages, including peer-to-peer and channel messages at a maximum frequency of 180 calls every three second.

    example
    client.sendMessageToPeer(
      { text: 'test peer message' }, // An RtmMessage object.
      'demoPeerId', // The uid of the remote user.
    ).then(sendResult => {
      if (sendResult.hasPeerReceived) {
        // Your code for handling the event when the remote user receives the message.
      } else {
        // Your code for handling the event when the message is received by the server but the remote user cannot be reached.
      }
    }).catch(error => {
      // Your code for handling the event when the message fails to be sent.
    });

    Parameters

    • message: RtmMessage

      The message to be sent.

    • peerId: string

      The uid of the peer user.

    • Optional options: SendMessageOptions

      Enables offline messaging. See SendMessageOptions.

      Note

      We do not support uids of the number type. We recommend using the toString() method to convert a non-string uid.

    Returns Promise<PeerMessageSendResult>

    The Promise resolves after the message is successfully sent. The value of the Promise indicates whether the peer user is online and receives the message.

setChannelAttributes

setLocalUserAttributes

  • setLocalUserAttributes(attributes: AttributesMap): Promise<void>
  • Substitutes the local user's attributes with new ones.

    Parameters

    Returns Promise<void>

    The Promise resolves after successfully setting the local user's attributes.

setParameters

  • Modifies the RtmClient instance configuration. The changes take effect immediately.

    deprecated

    This method is deprecated as of v1.4.2. Please use updateConfig instead.

    Parameters

    • config: RtmConfig

      Sets whether the SDK uploads logs, and sets the output level of logs. See RtmConfig.

    Returns void

subscribePeersOnlineStatus

  • subscribePeersOnlineStatus(peerIds: string[]): Promise<void>
  • Subscribes to the online status of the specified users.

    • When the method call succeeds, the SDK returns the RtmClientEvents.PeersOnlineStatusChanged 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 RtmClientEvents.PeersOnlineStatusChanged 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 RtmClientEvents.PeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server.

    Note

    • When you log out of the Agora RTM system, all the status that you subscribe to will be cleared. To keep the original subscription after you re-log in the system, you need to redo the whole subscription process.
    • When the SDK reconnects to the server from the state of being interrupted, the SDK automatically subscribes to the peers and states before the interruption without human intervention.

    Parameters

    • peerIds: string[]

      An array of the specified user IDs.

    Returns Promise<void>

unsubscribePeersOnlineStatus

  • unsubscribePeersOnlineStatus(peerIds: string[]): Promise<void>
  • Unsubscribes from the online status of the specified users.

    Parameters

    • peerIds: string[]

      An array of the specified user IDs.

    Returns Promise<void>

updateConfig

  • Modifies the RtmClient instance configuration. The changes take effect immediately.

    Parameters

    • config: RtmConfig

      Sets whether the SDK uploads logs, and sets the output level of logs. See RtmConfig.

    Returns void