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

文档中心





云信令（原实时消息）

Console 官网社区技术支持





Agora RTM Web API Reference

概览 Globals AgoraRTM RtmClient RtmMessage RtmChannel LocalInvitation RemoteInvitation RtmErrorCode RtmStatusCode

RTM 客户端类。你可以通过 AgoraRTM 上的 createInstance 方法创建 RTM 客户端实例。Agora RTM SDK 的入口。

Hierarchy

EventEmitter<RtmClientEvents>
- RtmClient

Index

Methods

addOrUpdateChannelAttributes

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

添加或更新某指定频道的属性。
- 如果属性已存在，该方法更新该频道的已有属性；
- 如果属性不存在，该方法增加该频道的属性。
Note
- 你无需加入指定频道即可为该频道更新频道属性。
- 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的 ID。
- attributes: AttributesMap
  
  待增加或更新的属性列表。
- Optional options: ChannelAttributeOptions
  
  频道属性操作选项。详见 ChannelAttributeOptions。
Returns Promise<void>

addOrUpdateLocalUserAttributes

addOrUpdateLocalUserAttributes(attributes: AttributesMap): Promise<void>

添加或更新本地用户的属性。
- 如果属性已存在，该方法更新本地用户的已有属性；
- 如果属性不存在，该方法增加本地用户的属性。
Parameters
- attributes: AttributesMap
  
  待增加或更新的属性列表。
Returns Promise<void>

该 Promise 会在添加或更新本地用户属性成功后 resolve。

clearChannelAttributes

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

清空某指定频道的属性。

Note
- 你无需加入指定频道即可清空该频道的属性。
- RtmClient.setChannelAttributes()、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys 和 clearChannelAttributes 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的频道 ID。
- Optional options: ChannelAttributeOptions
  
  频道属性操作选项。详见 ChannelAttributeOptions。
Returns Promise<void>

clearLocalUserAttributes

clearLocalUserAttributes(): Promise<void>

清空本地用户的所有属性。

Returns Promise<void>

该 Promise 会在清空本地用户属性成功后 resolve。

createChannel

createChannel(channelId: string): RtmChannel

该方法创建一个 RtmChannel 实例。

Parameters
- channelId: string
  频道名称。该字符串不可超过 64 字节。以下为支持的字符集范围:
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
  Note:
  - 请不要将 channelId 设为空、null，或字符串 "null"。
Returns RtmChannel

一个 RtmChannel 实例。

createLocalInvitation

createLocalInvitation(calleeId: string): LocalInvitation

该方法创建一个 LocalInvitation 实例。

Parameters
- calleeId: string
  
  被叫的 uid。
Returns LocalInvitation

一个 LocalInvitation 实例。

createMessage

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

创建一个消息实例，可用于发送点对点消息或频道消息。

Type parameters
- T: RtmMessage
  
  RtmMessage 类型别名。
Parameters
- message: Partial<T>
  
  一个包含 RtmMessage 中任意属性的对象。
Returns T

一个 RtmMessage 实例。你可以用这个实例发送点对点消息或频道消息。

deleteChannelAttributesByKeys

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

删除某指定频道的指定属性。

Note
- 你无需加入指定频道即可删除该频道的属性。
- 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys 和 clearChannelAttributes 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的 ID。
- attributeKeys: string[]
  
  属性名列表。
- Optional options: ChannelAttributeOptions
  
  频道属性操作选项。详见 ChannelAttributeOptions。
Returns Promise<void>

deleteLocalUserAttributesByKeys

deleteLocalUserAttributesByKeys(attributeKeys: string[]): Promise<void>

删除本地用户的指定属性。

Parameters
- attributeKeys: string[]
  
  属性名列表。
Returns Promise<void>

该 Promise 会在删除指定属性成功后 resolve。

getChannelAttributes

getChannelAttributes(channelId: string): Promise<ChannelAttributes>

查询某指定频道的全部属性。

Note
- 你无需加入指定频道即可查询该频道的属性。
- getChannelAttributes 和 getChannelAttributesByKeys 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的 ID。
Returns Promise<ChannelAttributes>

getChannelAttributesByKeys

getChannelAttributesByKeys(channelId: string, keys: string[]): Promise<ChannelAttributes>

查询某指定频道指定属性名的属性。

Note
- 你无需加入指定频道即可查询该频道的属性。
- getChannelAttributes 和 getChannelAttributesByKeys 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的频道 ID。
- keys: string[]
  
  频道属性名列表。
Returns Promise<ChannelAttributes>

getChannelMemberCount

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

查询单个或多个频道的成员人数。

Note
- 该方法的调用频率上限为每秒 1 次。
- 不支持一次查询超过 32 个频道的成员人数。
Parameters
- channelIds: string[]
  
  指定频道名列表。
Returns Promise<ChannelMemberCountResult>

getUserAttributes

getUserAttributes(userId: string): Promise<AttributesMap>

获取指定用户的全部属性。

Parameters
- userId: string
  
  指定用户的用户 ID。
Returns Promise<AttributesMap>

getUserAttributesByKeys

getUserAttributesByKeys(userId: string, attributeKeys: string[]): Promise<AttributesMap>

获取指定用户指定属性名的属性。

Parameters
- userId: string
  
  指定用户的用户 ID。
- attributeKeys: string[]
  
  属性名列表。
Returns Promise<AttributesMap>

login

用户登录 Agora RTM 系统。

note

在 RTM 和 RTC 结合使用的场景下，Agora 推荐你错时进行登录 RTM 系统和加入 RTC 频道的操作。

note

如果用户在不同的 RtmClient 实例中以相同用户 ID 登录，之前的登录将会失效，用户会被踢出之前加入的频道。

Parameters
- options: object
  - Optional token?: undefined | string
    
    可选的动态密钥，一般由客户的服务端获取。
  - uid: string
    登录 Agora RTM 系统的用户 ID。该字符串不可超过 64 字节。以下为支持的字符集范围:
    - 26 个小写英文字母 a-z
    - 26 个大写英文字母 A-Z
    - 10 个数字 0-9
    - 空格
    - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    Note
    - 请不要将 uid 设为空、null，或字符串 "null"。
    - uid 不支持 number 类型。建议调用 toString() 方法转化非 string 型 uid。
Returns Promise<void>

该 Promise 会在登录成功后 resolve。

logout

logout(): Promise<void>

退出登录，退出后自动断开连接和销毁回调监听。

Returns Promise<void>

该 Promise 会在登出成功并断开 WebSocket 连接后 resolve。

on

on<EventName>(eventName: EventName, listener: function): this

在该频道实例上添加 listener 函数到名为 eventName 的事件。其他 RtmClient 实例上的事件方法请参考 EventEmitter API 文档。

Type parameters
- EventName: keyof RtmClientEvents
Parameters
- eventName: EventName
  
  RTM 客户端事件的名称。事件列表请参考 RtmClientEvents 中的属性名。
- listener: function
  
  事件的回调函数。
  - - (...args: ListenerType<RtmClientEvents[EventName]>): any
    - Parameters
      - Rest ...args: ListenerType<RtmClientEvents[EventName]>
      Returns any
Returns this

queryPeersBySubscriptionOption

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

获取某特定内容被订阅的用户列表。

Parameters
- option: PeerSubscriptionOption
  
  被订阅的类型。详见 RtmStatusCode.PeerSubscriptionOption。
Returns Promise<string[]>

queryPeersOnlineStatus

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

查询指定用户的在线状态。

Parameters
- peerIds: string[]
  
  用户 ID 列表。用户 ID 的数量不能超过 256。
Returns Promise<PeersOnlineStatusResult>

renewToken

renewToken(token: string): Promise<void>

更新当前 Token。

Parameters
- token: string
  
  新的 Token。
Returns Promise<void>

sendMessageToPeer

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

本地用户（发送者）向指定用户（接收者）发送点对点消息或点对点的离线消息。

发送消息（包括点对点消息和频道消息）的频率上限为 180 次每 3 秒。
example
```
client.sendMessageToPeer(
  { text: 'test peer message' }, // 一个 RtmMessage 实例。
  'PeerId', // 对端用户的 uid。
).then(sendResult => {
  if (sendResult.hasPeerReceived) {
    // 你的代码：远端用户收到消息事件。
  } else {
    // 你的代码：服务器已收到消息，对端未收到消息。
  }
}).catch(error => {
  // 你的代码：点对点消息发送失败。
});
```
Parameters
- message: RtmMessage
  
  要发送的文字消息。
- peerId: string
  
  远端用户的 uid。
  
  Note
  uid 不支持 number 类型。建议调用 toString() 方法转化非 string 型 uid。
Returns Promise<PeerMessageSendResult>

该 Promise 会在发送成功后 resolve。Promise 的值代表对方是否在线并接收成功。

setChannelAttributes

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

全量设置某指定频道的属性。

Note
- 你无需加入指定频道即可为该频道设置频道属性。
- 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率限制为每 5 秒 10 次。
Parameters
- channelId: string
  
  该指定频道的频道 ID。
- attributes: AttributesMap
  
  频道属性列表实例。
- Optional options: ChannelAttributeOptions
  
  频道属性操作选项。详见 ChannelAttributeOptions。
Returns Promise<void>

setLocalUserAttributes

setLocalUserAttributes(attributes: AttributesMap): Promise<void>

全量设置本地用户的属性。

Parameters
- attributes: AttributesMap
  
  新的属性。
Returns Promise<void>

该 Promise 会在设置本地用户属性成功后 resolve。

setParameters

setParameters(config: RtmConfig): void

修改 RtmClient 实例配置。修改实时生效。

deprecated

该方法自 v1.4.2 起已废弃，请使用 updateConfig。

Parameters
- config: RtmConfig
  
  设置 SDK 是否上传日志以及日志的输出等级。详见 RtmConfig。
Returns void

subscribePeersOnlineStatus

subscribePeersOnlineStatus(peerIds: string[]): Promise<void>

订阅指定单个或多个用户的在线状态。
- 首次订阅成功后，SDK 会通过 RtmClientEvents.PeersOnlineStatusChanged 回调返回被订阅用户在线状态。
- 每当被订阅用户在线状态发生变化时，SDK 都会通过 RtmClientEvents.PeersOnlineStatusChanged 回调通知订阅方。
- 如果 SDK 在断线重连过程中有被订阅用户的在线状态发生改变，SDK 会在重连成功时通过 RtmClientEvents.PeersOnlineStatusChanged 回调通知订阅方。
Note
- 用户登出 Agora RTM 系统后，所有之前的订阅内容都会被清空；重新登录后，如需保留之前订阅内容则需重新订阅。
- SDK 会在网络连接中断时进入断线重连状态。重连成功时 SDK 会自动重新订阅之前订阅用户，无需人为干预。
Parameters
- peerIds: string[]
Returns Promise<void>

unsubscribePeersOnlineStatus

unsubscribePeersOnlineStatus(peerIds: string[]): Promise<void>

退订指定单个或多个用户的在线状态。

Parameters
- peerIds: string[]
  
  被退订用户的用户 ID 阵列。
Returns Promise<void>

updateConfig

updateConfig(config: RtmConfig): void

修改 RtmClient 实例配置。修改实时生效。

Parameters
- config: RtmConfig
  
  设置 SDK 是否上传日志以及日志的输出等级。详见 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