Agora RTM Web SDK 是通过 HTML 网页加载的 JavaScript 库。Agora RTM Web SDK 库在网页浏览器中通过 API 调用声网的实时消息服务。

AgoraRTM 是 Agora RTM SDK 的导出模块。使用 <script> 标签引入 SDK 时,产生名为 AgoraRTM 的全局变量,该变量含有该模块的所有成员。

请分别调用 RtmClient.onRtmChannel.on 方法添加 RtmClientRtmChannel 对象的监听器。

Agora RTM Web SDK 提供以下功能:

登录登出相关

方法 描述
createInstance 创建一个 RtmClient 实例。
  • 错误码详见 CreateInstanceError
  • login 登录 Agora RTM 系统。
  • 错误码详见 LoginError
  • logout 退出登录,退出后自动断开连接和销毁回调监听。
  • 错误码详见 LogoutError
  • 事件 描述
    ConnectionStateChanged 通知 SDK 与 Agora RTM 系统的连接状态发生了改变。

    点对点消息

    方法 描述
    sendMessageToPeer 向指定用户(接收者)发送点对点消息或点对点的离线消息。
  • Promise<PeerMessageSendResult> 返回本次消息投递结果。
  • 错误码详见 PeerMessageError
  • 事件 描述
    MessageFromPeer 收到来自对端的点对点消息。

    查询用户在线状态

    方法 描述
    queryPeersOnlineStatus 查询指定用户的在线状态。
  • 指定用户的在线状态由 Promise<PeersOnlineStatusResult> 返回。
  • 错误码详见 QueryPeersOnlineStatusError
  • 订阅或退订单个或多个指定用户的在线状态

    Method Description
    subscribePeersOnlineStatus 订阅指定单个或多个用户的在线状态。
  • 错误码详见 PeerSubscriptionStatusError
  • unsubscribePeersOnlineStatus 解除订阅指定单个或多个用户的在线状态。
  • 错误码详见 PeerSubscriptionStatusError
  • queryPeersBySubscriptionOption 获取某特定内容被订阅的用户列表。
  • 订阅类型详见 PeerSubscriptionOption
  • 错误码详见 QueryPeersBySubscriptionOptionError
  • Event Description
    PeersOnlineStatusChanged 被订阅用户在线状态改变回调。
  • 用户在线状态详见 PeersOnlineStatusMap
  • 用户属性增删改查

    方法 描述
    setLocalUserAttributes 全量设置本地用户的属性。
  • 待设置的用户属性详见 AttributesMap
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • addOrUpdateLocalUserAttributes 添加或更新本地用户的属性。
  • 待添加或更新的用户属性详见 AttributesMap
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • deleteLocalUserAttributesByKeys 删除本地用户的指定属性。
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • clearLocalUserAttributes 清空本地用户的属性。
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • getUserAttributes 获取指定用户的全部属性。
  • 用户属性由 Promise<AttributesMap> 返回。
  • 错误码详见 AttributeOperationError
  • getUserAttributesByKeys 获取指定用户指定属性名的属性。
  • 用户属性由 Promise<AttributesMap> 返回。
  • 错误码详见 AttributeOperationError
  • 频道属性增删改查

    方法 描述
    setChannelAttributes 全量设置某指定频道的属性。
  • 待设置的频道属性详见 AttributesMap
  • 方法调用结果由 Promise<void> 返回。
  • 本次频道属性操作选项详见 ChannelAttributeOptions
  • 错误码详见 AttributeOperationError
  • addOrUpdateChannelAttributes 添加或更新某指定频道的属性。
  • 待添加或更新的频道属性详见 AttributesMap
  • 本次频道属性操作选项详见 ChannelAttributeOptions
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • deleteChannelAttributesByKeys 删除某指定频道的指定属性。
  • 本次频道属性操作选项详见 ChannelAttributeOptions
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • clearChannelAttributes 清空某指定频道的属性。
  • 本次频道属性操作选项详见 ChannelAttributeOptions
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 AttributeOperationError
  • getChannelAttributes 查询某指定频道的全部属性。
  • 频道属性由 Promise<ChannelAttributes> 返回。
  • 错误码详见 AttributeOperationError
  • getChannelAttributesByKeys 查询某指定频道指定属性名的属性。
  • 频道属性由 Promise<ChannelAttributes> 返回。
  • 错误码详见 AttributeOperationError
  • 频道属性更新事件 描述
    AttributesUpdated 当频道属性更新时返回当前频道的所有属性。
  • 当前频道的所有属性详见 ChannelAttributes
  • 查询单个或多个频道的成员人数

    方法 描述
    getChannelMemberCount 查询单个或多个频道的成员人数。
  • 用户无需加入指定频道即可调用该方法。
  • 频道和人数由 Promise<ChannelMemberCountResult> 返回。
  • 错误码详见 GetChannelMemberCountErrCode
  • 加入离开频道相关

    方法 描述
    createChannel 创建一个 RtmChannel 实例。
  • 错误码详见 CreateChannelError
  • join 加入频道。加入频道成功后可收到该频道消息和频道用户进出通知。
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 JoinChannelError
  • leave 离开频道。不再接收频道消息和频道用户进出通知。
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 LeaveChannelError
  • 事件 描述
    MemberJoined 远端用户加入频道回调。
    MemberLeft 远端用户离开频道回调。
    MemberCountUpdated 频道成员人数更新回调。返回最新频道成员人数。

    频道消息

    方法 描述
    sendMessage 供频道成员向所在频道发送频道消息。
  • 本次消息发送选项参见 SendMessageOptions
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 ChannelMessageError
  • 事件 描述
    ChannelMessage 收到频道消息回调。

    获取频道成员列表

    方法 描述
    getMembers 获取频道成员列表。
  • 方法调用结果由 Promise<string[]> 返回。
  • 错误码详见 GetMembersError
  • 呼叫邀请管理

    • 主叫取消已发送的呼叫邀请的 API 时序图:

    • 被叫接收或拒绝收到的呼叫邀请的 API 时序图:

    供主叫调用的方法 描述
    createLocalInvitation 供主叫创建一个 LocalInvitation 实例。
  • 错误码详见 InvitationApiCallError
  • send 供主叫发送呼叫邀请给对端。
  • 错误码详见 InvitationApiCallError
  • cancel 供主叫取消已发送的呼叫邀请。
  • 错误码详见 InvitationApiCallError
  • 供被叫调用的方法 描述
    accept 供被叫接受呼叫邀请。
  • 错误码详见 InvitationApiCallError
  • refuse 供被叫拒绝呼叫邀请。
  • 错误码详见 InvitationApiCallError
  • 返回给主叫的事件 描述
    LocalInvitationReceivedByPeer 返回给主叫的回调:被叫已收到呼叫邀请。
    LocalInvitationCanceled 返回给主叫的回调:呼叫邀请已被取消。
    LocalInvitationAccepted 返回给主叫的回调:被叫已接受呼叫邀请。
    LocalInvitationRefused 返回给主叫的回调:被叫已拒绝呼叫邀请。
    LocalInvitationFailure 返回给主叫的回调:呼叫邀请过程失败。
  • 错误码详见 LocalInvitationFailureReason
  • 返回给被叫的事件 描述
    RemoteInvitationReceived 返回给被叫的回调:收到一条呼叫邀请。SDK 会同时返回一个RemoteInvitation 对象供被叫管理。
    RemoteInvitationCanceled 返回给被叫的回调:主叫已取消呼叫邀请。
    RemoteInvitationAccepted 返回给被叫的回调:接受呼叫邀请成功。
    RemoteInvitationRefused 返回给被叫的回调:拒绝呼叫邀请成功。
    RemoteInvitationFailure 返回给被叫的回调:呼叫邀请过程失败。
  • 错误码详见 RemoteInvitationFailureReason
  • 更新 Token

    方法 描述
    renewToken 更新当前 Token。
  • 方法调用结果由 Promise<void> 返回。
  • 错误码详见 RenewTokenError
  • 事件 描述
    TokenExpired Token 过期回调。

    日志设置与版本查询

    变量 描述
    enableLogUpload 是否启用日志上传。
  • 详见 createInstance 方法的配置参数 RtmParameters ,或 setParameters 方法。
  • logFilter 设置 SDK 的日志输出等级。
  • 详见 createInstance 方法的配置参数 RtmParameters ,或 setParameters 方法。
  • VERSION Agora RTM SDK 的当前版本信息。

    定制方法

    方法 描述
    setParameters 配置 SDK 提供技术预览或特别定制功能。
  • 配置参数详见 RtmParameters