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

RtmClient is the entry point of the Agora RTM SDK. You can call the createInstance method of AgoraRTM to create an RtmClient instance.

Hierarchy

EventEmitter<RtmClientEvents>
- RtmClient

Methods

addOrUpdateChannelAttributes

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

Adds or updates the attribute(s) of a specified channel.

This method updates the specified channel's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) to the channel if it does not.

Note
For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 queries 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 attribute(s).

This method updates the local user's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) 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
For RtmClient.setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 queries 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:
  - The 26 lowercase English letters: a to z
  - The 26 uppercase English letters: A to Z
  - The 10 numbers: 0 to 9
  - Space
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
  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.

deleteChannelAttributesByKeys

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

Deletes the local user's attributes using attribute keys.

Note
For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 queries 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
For getChannelAttributes and getChannelAttributesByKeys taken together: the call frequency limit is 10 queries 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
For getChannelAttributes and getChannelAttributesByKeys taken together: the call frequency limit is 10 queries 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<ChannelMemberCounts>

Gets the member count of specified channel(s).

Note
- The call frequency limit for this method is one query 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 ID(s).
Returns Promise<ChannelMemberCounts>

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

Allows a user to log in the Agora RTM system.

note

If you log in with the same uid from a different instance, you 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:
    - The 26 lowercase English letters: a to z
    - The 26 uppercase English letters: A to Z
    - The 10 numbers: 0 to 9
    - Space
    - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    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 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

queryPeersOnlineStatus

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

Queries the online status of the specified user(s).

Parameters
- peerIds: string[]
  
  A list of the user IDs.
Returns Promise<PeerOnlineStatuses>

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 speed of 60 queries per 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 resolve 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
For setLocalUserAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys, and clearChannelAttributes taken together: the call frequency limit is 10 queries 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(params: RtmParameters): void

Configures the SDK to provide technical preview functionalities or special customizations.

Parameters
- params: RtmParameters
  
  See RtmParameters.
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

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<ChannelMemberCounts>

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

eventName: EventName

listener: function

Parameters

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

Returns any

Returns this