RtmClient | Signaling (previously RTM) SDK v1.5.1 API Reference for Web

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

EventEmitter<RtmClientEvents>
- RtmClient

Index

Methods

addOrUpdateChannelAttributes

addOrUpdateChannelAttributes(channelId: string, attributes: AttributesMap, options?: ChannelAttributeOptions): Promise<void>

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
- You do not have to join the specified channel to update its attributes.
- The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
- For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 calls every five seconds.
Parameters
- channelId: string
  
  The channel ID of the specified channel.
- attributes: AttributesMap
  
  An array of channel attributes.
- Optional options: ChannelAttributeOptions
  
  Options for this attribute operation. See ChannelAttributeOptions.
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

clearChannelAttributes(channelId: string, options?: ChannelAttributeOptions): Promise<void>

Clears all attributes of a specified channel.

Note
- You do not have to join the specified channel to clear its attributes.
- For RtmClient.setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 calls every five seconds.
Parameters
- channelId: string
  
  The channel ID of the specified channel.
- Optional options: ChannelAttributeOptions
  
  Options for this attribute operation. See ChannelAttributeOptions.
Returns Promise<void>

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

createChannel(channelId: string): RtmChannel

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

createLocalInvitation(calleeId: string): LocalInvitation

Creates a LocalInvitation instance.

Parameters
- calleeId: string
  
  The uid of the callee.
Returns LocalInvitation

A LocalInvitation instance.

createMediaMessageByUploading

createMediaMessageByUploading(payload: Blob, params?: undefined | object, transHandler?: MediaTransferHandler): Promise<RtmFileMessage>
createMediaMessageByUploading(payload: Blob, params?: undefined | object, transHandler?: MediaTransferHandler): Promise<RtmImageMessage>

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
- T: RtmMessage
  
  A RtmMessage type.
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>

Deletes the local user's attributes using attribute keys.

Note
- You do not have to join the specified channel to delete its attributes.
- The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
- For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 calls every five seconds.
Parameters
- channelId: string
  
  The channel ID of the specified channel.
- attributeKeys: string[]
  
  A list of channel attribute keys.
- Optional options: ChannelAttributeOptions
  
  Options for this attribute operation. See ChannelAttributeOptions.
Returns 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

downloadMedia(mediaId: string, transHandler?: MediaTransferHandler): Promise<Blob>

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

getChannelAttributes(channelId: string): Promise<ChannelAttributes>

Gets all attributes of a specified channel.

Note
- You do not have to join the specified channel to delete its attributes.
- For getChannelAttributes and getChannelAttributesByKeys taken together: the call frequency limit is 10 calls every five seconds.
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
- You do not have to join the specified channel to get its attributes.
- For getChannelAttributes and getChannelAttributesByKeys taken together: the call frequency limit is 10 calls every five seconds.
Parameters
- channelId: string
  
  The ID of the specified channel.
- keys: string[]
  
  An array of attribute keys.
Returns Promise<ChannelAttributes>

getChannelMemberCount

getChannelMemberCount(channelIds: string[]): Promise<ChannelMemberCountResult>

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

getUserAttributes(userId: string): Promise<AttributesMap>

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

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

queryPeersBySubscriptionOption(option: PeerSubscriptionOption): Promise<string[]>

Gets a list of the peers, to whose specific status you have subscribed.

Parameters
- option: PeerSubscriptionOption
  
  The status type, to which you have subscribed. See RtmStatusCode.PeerSubscriptionOption.
Returns Promise<string[]>

queryPeersOnlineStatus

queryPeersOnlineStatus(peerIds: string[]): Promise<PeersOnlineStatusResult>

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

sendMessageToPeer(message: RtmMessage, peerId: string, options?: SendMessageOptions): Promise<PeerMessageSendResult>

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

setChannelAttributes(channelId: string, attributes: AttributesMap, options?: ChannelAttributeOptions): Promise<void>

Sets the attributes of a specified channel with new ones.

Note
- You do not have to join the specified channel to reset its attributes.
- The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
- For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 calls every five seconds.
Parameters
- channelId: string
  
  The channel ID of the specified channel.
- attributes: AttributesMap
  
  An array of channel attributes.
- Optional options: ChannelAttributeOptions
  
  Options for this attribute operation. See ChannelAttributeOptions.
Returns Promise<void>

setLocalUserAttributes

setLocalUserAttributes(attributes: AttributesMap): Promise<void>

Substitutes the local user's attributes with new ones.

Parameters
- attributes: AttributesMap
  
  The new attributes.
Returns Promise<void>

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

setParameters

setParameters(config: RtmConfig): void

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

updateConfig(config: RtmConfig): void

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

Hierarchy

Index

Methods

Methods

addOrUpdateChannelAttributes

Parameters

channelId: string

attributes: AttributesMap

Optional options: ChannelAttributeOptions

Returns Promise<void>

addOrUpdateLocalUserAttributes

Parameters

attributes: AttributesMap

Returns Promise<void>

clearChannelAttributes

Parameters

channelId: string

Optional options: ChannelAttributeOptions

Returns Promise<void>

clearLocalUserAttributes

Returns Promise<void>

createChannel

Parameters

channelId: string

Returns RtmChannel

createLocalInvitation

Parameters

calleeId: string

Returns LocalInvitation

createMediaMessageByUploading

Parameters

payload: Blob

Optional params: undefined | object

Optional transHandler: MediaTransferHandler

Returns Promise<RtmFileMessage>

Parameters

payload: Blob

Optional params: undefined | object

Optional transHandler: MediaTransferHandler

Returns Promise<RtmImageMessage>

createMessage

Type parameters

T: RtmMessage

Parameters

message: Partial<T>

Returns T

deleteChannelAttributesByKeys

Parameters

channelId: string

attributeKeys: string[]

Optional options: ChannelAttributeOptions

Returns Promise<void>

deleteLocalUserAttributesByKeys

Parameters

attributeKeys: string[]

Returns Promise<void>

downloadMedia

Parameters

mediaId: string

Optional transHandler: MediaTransferHandler

Returns Promise<Blob>

getChannelAttributes

Parameters

channelId: string

Returns Promise<ChannelAttributes>

getChannelAttributesByKeys

Parameters

channelId: string

keys: string[]

Returns Promise<ChannelAttributes>

getChannelMemberCount

Parameters

channelIds: string[]

Returns Promise<ChannelMemberCountResult>

getUserAttributes

Parameters

userId: string

Returns Promise<AttributesMap>

getUserAttributesByKeys

Parameters