Agora Real-time Messaging (RTM) SDK 提供了稳定可靠、低延时、高并发的全球消息云服务,帮助你快速构建实时场景。

如无特别说明,本页列出的大多数 RTM 核心业务方法都应在调用 login 方法成功收到 onSuccess 回调后才能调用。

Agora RTM SDK 提供以下功能:

登录登出相关

SDK 与 RTM 服务器的连接状态是 RTM 开发过程需要理解的核心概念,详见连接状态管理

方法 描述
createInstance 创建并返回一个 RtmClient 实例。
login 用户登录 Agora RTM 系统。
logout 用户登出 Agora RTM 系统。
release 释放该 RtmClient 实例使用的所有资源。
事件 描述
onConnectionStateChanged SDK 与 Agora RTM 系统的连接状态发生改变回调。

点对点消息

方法 描述
createMessage 创建并返回一个空文本 RtmMessage 消息实例。
createMessage 创建并返回一个文本 RtmMessage 消息实例。
createMessage 创建并返回一个自定义二进制 RtmMessage 消息实例。
createMessage 创建并返回一个包含文字描述的自定义二进制 RtmMessage 消息实例。
sendMessageToPeer 向指定用户发送点对点消息或点对点的离线消息。
事件 描述
onMessageReceived 收到点对点消息回调。

查询单个或多个用户在线状态

方法 描述
queryPeersOnlineStatus 获取用户在线状态。

订阅或取消订阅单个或多个指定用户的在线状态

方法 描述
subscribePeersOnlineStatus 订阅单个或多个用户的在线状态。
unsubscribePeersOnlineStatus 取消订阅单个或多个用户的在线状态。
queryPeersBySubscriptionOption 根据订阅内容获取用户列表。
事件 描述
onPeersOnlineStatusChanged 被订阅用户在线状态改变回调。

用户属性增删改查

方法 描述
setLocalUserAttributes 全量设置本地用户的属性。
addOrUpdateLocalUserAttributes 添加或更新本地用户的属性。
deleteLocalUserAttributesByKeys 删除本地用户的指定属性。
clearLocalUserAttributes 清空本地用户的属性。
getUserAttributes 获取指定用户的全部属性。
getUserAttributesByKeys 获取指定用户指定属性名的属性。

频道属性增删改查

方法 描述
setChannelAttributes 全量设置某指定频道的属性。
addOrUpdateChannelAttributes 添加或更新某指定频道的属性。
deleteChannelAttributesByKeys 删除某指定频道的指定属性。
clearChannelAttributes 清空某指定频道的属性。
getChannelAttributes 获取某指定频道的全部属性。
getChannelAttributesByKeys 获取某指定频道指定属性名的属性。
频道属性更新事件 描述
onAttributesUpdated 当频道属性更新时返回当前频道的所有属性。

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

方法 描述
getChannelMemberCount 查询单个或多个频道的成员人数。

上传和下载文件或图片

方法 描述
createFileMessageByMediaId 通过 media ID 创建一个 RtmFileMessage 文件消息实例。
createImageMessageByMediaId 通过 media ID 创建一个 RtmImageMessage 图片消息实例。
createFileMessageByUploading 上传一个文件到 Agora 服务器以获取一个 RtmFileMessage 文件消息实例。
createImageMessageByUploading 上传一个图片到 Agora 服务器以获取一个 RtmImageMessage 图片消息实例。
downloadMediaToMemory 通过 media ID 从 Agora 服务器下载文件或图片至本地内存。
downloadMediaToFile 通过 media ID 从 Agora 服务器下载文件或图片至本地指定地址。
cancelMediaUpload 通过 request ID 取消一个正在进行的文件或图片上传任务。
cancelMediaDownload 通过 request ID 取消一个正在进行的文件或图片下载任务。
事件 描述
onImageMessageReceived 收到频道图片消息回调。
onFileMessageReceived 收到频道文件消息回调。
onImageMessageReceivedFromPeer 收到点对点图片消息回调。
onFileMessageReceivedFromPeer 收到点对点文件消息回调。
onMediaUploadingProgress 上传任务的上传进度回调。
onMediaDownloadingProgress

下载任务的下载进度回调。

加入离开频道相关

方法 描述
createChannel 创建一个 RtmChannel 频道实例。
join 用户加入频道。一个用户最多可以同时加入 20 个 RTM 频道。
leave 用户离开频道。
getId 获取频道 ID。
release 释放当前频道的所有资源。
事件 描述
onMemberJoined 远端用户加入频道回调。
onMemberLeft 远端频道成员离开频道回调。
onMemberCountUpdated 频道成员人数更新回调。返回最新频道成员人数。

频道消息

方法 描述
createMessage 创建并返回一个空文本 RtmMessage 消息实例。
createMessage 创建并返回一个文本 RtmMessage 消息实例。
createMessage 创建并返回一个自定义二进制 RtmMessage 消息实例。
createMessage 创建并返回一个包含文字描述的自定义二进制 RtmMessage 消息实例。
sendMessage 发送频道消息。
事件 描述
RtmChannelListener.onMessageReceived 收到频道消息。

获取频道成员列表

方法 描述
getMembers 获取频道成员列表。

呼叫邀请管理

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

  • 被叫接受呼叫邀请的 API 时序图:

  • 被叫拒绝呼叫邀请的 API 时序图:

呼叫管理器获取方法 描述
getRtmCallManager 获取一个 RtmCallManager 呼叫邀请管理器对象。
setEventListener 设置 RtmCallManager 实例的监听器。
供主叫调用的方法 描述
createLocalInvitation 供主叫创建、管理一个 LocalInvitation 呼叫邀请对象。
sendLocalInvitation 供主叫向指定用户发送呼叫邀请。
cancelLocalInvitation 供主叫取消一个呼叫邀请。
供被叫调用的方法 描述
acceptRemoteInvitation 供被叫接受来自对方的呼叫邀请。
refuseRemoteInvitation 拒绝来自对方的呼叫邀请。
返回给主叫的事件 描述
onLocalInvitationReceivedByPeer 返回给主叫的回调:被叫已收到呼叫邀请。
onLocalInvitationAccepted 返回给主叫的回调:被叫已接受呼叫邀请。
onLocalInvitationRefused 返回给主叫的回调:被叫已拒绝呼叫邀请。
onLocalInvitationCanceled 返回给主叫的回调:呼叫邀请已被成功取消。
onLocalInvitationFailure 返回给主叫的回调:发出的呼叫邀请过程失败。
返回给被叫的事件 描述
onRemoteInvitationReceived 返回给被叫的回调:收到一条呼叫邀请。SDK 会同时返回一个 RemoteInvitation 对象供被叫管理。
onRemoteInvitationAccepted 返回给被叫的回调:接受呼叫邀请成功。
onRemoteInvitationRefused 返回给被叫的回调:拒绝呼叫邀请成功。
onRemoteInvitationCanceled 返回给被叫的回调:主叫已取消呼叫邀请。
onRemoteInvitationFailure 返回给被叫的回调:来自主叫的邀请过程失败。

更新 Token

方法 描述
renewToken 更新当前的 RTM Token。
事件 描述
onTokenExpired (SDK 断线重连时触发)当前使用的 RTM Token 已超过 24 小时的签发有效期。

日志设置与版本查询

  • 日志相关操作在创建 RtmClient 实例后即可进行,无需等到调用 login 方法成功。
  • 版本查询操作为静态方法,可在创建并初始化 RtmClient 实例前进行。
方法 描述
setLogFile 设定日志文件的默认地址。
setLogFilter 设置日志输出等级。
setLogFileSize 设置 SDK 输出的单个日志文件的大小,单位为 KB。 SDK 设有 2 个大小相同的日志文件。
getSdkVersion 获取 Agora RTM SDK 的版本信息。

定制方法

方法 描述
setParameters 通过 JSON 配置 SDK 提供技术预览或特别定制功能。

区域限定

方法 描述
setRtmServiceContext 设置所有 RtmClient 实例的上下文。你在成功调用此方法之后创建的所有 RtmClient 实例都符合此方法设置的上下文。