RTM 1.x 将于近期下架，各版本退休日期和替代方案详见退休政策。

Documentation





Real-time Messaging

Console 官网 Community Technical support





Agora RTM Web API Reference

Index AgoraRTM RtmClient RtmMessage RtmChannel LocalInvitation RemoteInvitation RtmEvents RtmErrorCode RtmStatusCode

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.

createMessage

createMessage<T>(message: Partial<T>): T

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.

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): 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.
  
  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

Agora RTM Web API Reference

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

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>

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

userId: string

attributeKeys: string[]

Returns Promise<AttributesMap>

login

Parameters

options: object

Optional token?: undefined | string

uid: string

Returns Promise<void>

logout

Returns Promise<void>

on

Type parameters

EventName: keyof RtmClientEvents

Parameters