rongCloudIM
来自于:融云官方立即使用
注意事项:
使用该模块需要在config.xml中进行如下配置(可参考:https://docs.apicloud.com/Dev-Guide/app-config-manual#35-2):
<intent-filter>
<action name="android.intent.action.VIEW"/>
<category name="android.intent.category.DEFAULT"/>
<data scheme="rong" host="io.rong.fast" pathPrefix="/conversation/"/>
</intent-filter>
<intent-filter>
<action name="android.intent.action.VIEW" />
<category name="android.intent.category.DEFAULT" />
<data host="你的包名" path="/conversationlist" scheme="rong" />
</intent-filter>
<intent-filter>
<action name="android.intent.action.VIEW" />
<category name="android.intent.category.DEFAULT" />
<data host="你的包名" pathPrefix="/push_message" scheme="rong" />
</intent-filter>
其中 data中的host为集成应用的包名
初始化和连接
消息的接收和发送
会话
会话通知状态
消息的读取和删除
未读消息数
消息的状态
消息回执
文字消息草稿
讨论组
聊天室
黑名单
消息通知免打扰
概述
rongCloudIM 是基于 rongCloud2 模块把音视频相关接口去掉的版本
融云 Rong Cloud 是国内首家专业的即时通讯云服务提供商,专注为互联网、移动互联网开发者提供即时通讯基础能力和云端服务。通过融云平台,开发者不必搭建服务端硬件环境,就可以将即时通讯、实时网络能力快速集成至应用中。
rongCloudIM 封装了融云即时通讯能力库 IMLib SDK 的 API,对融云的相关接口做了一一对应的封装,功能详情可参考目录。
使用 rongCloudIM 模块之前,请先 注册 融云的开发者帐号并申请创建 App,创建 App 后,可以在 开发者后台 获取 App Key 和 App Secret 用于开发。
开发前请先认真阅读相关的 融云开发文档和视频。
iOS 平台推送通知功能详解
本文主要介绍了使用融云 IM 时,何时会收到远程推送、如何使用远程推送、如何获取远程推送的内容。
何时会收到远程推
在使用远程推送之前,您需要先了解融云 SDK 的运行状态。
融云SDK的运行状态及其内容的接受
融云 SDK 根据 iOS App 运行的特性,主要有以下三种运行状态:
1、 前台状态 如字面意思,App 前台可见时模块处于前台状态。此时 App 使用融云的长连接通道来收发消息。
2、 后台活动状态 当 App 进入后台 2 分钟之内,模块于后台活跃状态。此时 App 使用融云的长连接通道接收消息。
3、 后台暂停状态当 App 进入后台 2 分钟之后或被杀进程或被冻结,模块处于后台暂停状态。此时融云的长连接通道会断开,融云 Server 会通过 APNs 将消息以远程推送的形式下发到客户端。 此状态下如果有人给该用户发送消息,融云的服务器会根据 deviceToken 和推送证书将消息发送到苹果推送服务器,苹果服务器会将该消息推送到客户端。
如何使用远程推送
此过程的 1-4 步骤请参考融云官方的 推送开发指南----如何使用远程推送。其中涉及到的 AppID即为 Bundle Identifie,与 APICloud 平台上的包名是同一个东西,在 APICloud 平台上应用的概览里可以查看。
- 为 App 开启远程推送服务
- 生成并上传 P12 证书
- 融云开发者平台上传 p12 证书
- 生成 provisioning profile 文件
- 将 provisioning profile 文件上传 APICloud 平台
- 在 APICloud 平台云编译出 ipa 安装包并安装(正式版发布到苹果商店,通过苹果商店下载安装)
- 用户允许推送
以上步骤都已经实现后,还需要使用您 App 的用户允许通知,才能收到远程推送。您可以在设备的设置应用中,查看当前App是否允许通知。
如何获取远程推送的内容
远程推送内容的获取
点击通知栏的远程推送时,如果此时 App 已经被系统冻结,则APICloud会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:
api.addEventListener({
name: 'noticeclicked'
}, function(ret) {
if (ret && ret.value) {
var result = ret.value;
}
})
如果 App 未被系统冻结,则您在 setOnReceiveMessageListener 接口中可以捕获该消息,详情参考 setOnReceiveMessageListener 接口说明。
音视频通话推送功能详细请参考 VoIP 推送设置文档(1-6)。其中步骤6参考 APICloud 平台关于后台运行权限的配置。
android集成小米推送
- 集成小米推送需要依赖APICloud平台的mipush模块
- 在小米开发者平台申请应用,并将appid和appkey配置到init接口中
- 在小米开发者平台申请应用后,需要将APP Secret配置到融云控制台的应用标识中
android集成华为推送
- 集成华为推送需要依赖APICloud平台的huaweiPush模块,并在config中配置huaweiPush模块
- 在华为开发者平台申请应用,并将init接口中的huaweiPush参数设置为true
- 在华为开发者平台申请应用后,需要将华为的相关参数配置到融云控制台的应用标识中
注意
- 从3.1.5版本开始,android上点击推送过来的消息,开发者可以在appintent事件中接收到该消息的内容,可以从appParam参数的rong_params字段中获取;
模块接口
init
初始化融云 SDK,调用 connect 连接前务必保证调用此方法
调用前请在 config.xml 中设置内容如下:
<feature name="rongCloudIM">
<param name="appKey" value="此处填写 App Key 值" />
</feature>
其中 value 的值请替换为您在融云开发者平台上申请的 App Key 值
init(params, callback(ret, err))
params
miPush:
- 类型:JSON对象
- 描述:(可选项)配置小米推送的信息
- 默认值:无
- 内部字段:
appId: //字符串类型;小米后台申请的appid appKey: //字符串类型;小米后台申请的appKey
huaweiPush:
- 类型:布尔类型
- 描述:(可选项) 是否集成华为推送
- 默认值:false
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:初始化的状态,如果 config.xml 中没有设置 appKey 值,会导致失败,错误信息为参数错误
- 内部字段:
{
status: 'success', // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: -10002 // 错误码
}
错误说明:
错误码 | 说明 |
---|---|
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
rong.init(function(ret, err) {
if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
configurationParameter
配置推送相关参数
configurationParameter({params})
params
alertTitle:
- 类型:字符串
- 默认值:您收到了一条新消息
- 描述:进入后台两分钟内收到通知的显示内容,不传则显示消息内容
showNickname:
- 类型:布尔
- 默认值:false
- 描述:推送提示是否显示昵称,注:设置昵称的方式为:在发送消息接口的extra字段中填写昵称信息,格式为extra:{userInfo:{nickName:"用户昵称"}}
示例代码
var rong = api.require('rongCloudIM');
rong.configurationParameter({
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
connect
连接融云 IM 服务器,进行后续各种方法操作前务必要先调用此方法
connect({params}, callback(ret, err))
params
token:
- 类型:字符串
- 默认值:无
- 描述:从服务端获取的用户身份令牌(Token)
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的登录成功或者失败的状态
- 内部字段:
{
status: 'success', // 状态码:success / error
result:
{
userId: '9527' // 当前登录的用户 Id
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 31004 // 错误码
}
错误说明:
错误码 | 说明 |
---|---|
31003 | 服务器不可用 |
31004 | 错误的令牌(Token),Token 解析失败,请重新向身份认证服务器获取 Token |
31002 | 可能是错误的 App Key,或者 App Key 被服务器积极拒绝 |
33002 | 服务端数据库错误 |
31000 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10002 | 输入参数错误 |
-1000 | (此错误只发生在 iOS)当已经 connect 成功后再次 connect 时会返回此错误 |
示例代码
var rong = api.require('rongCloudIM');
rong.init(function(ret, err) {
if (ret.status == 'error')
api.toast({ msg: err.code });
});
rong.connect({
token: 'ThptTWyiPPPvZHvuSiuri82yq+hfEluLjZ78E1qo4hEVSFQNpqdoPu406urMWKN4Z3/olWR+v9JVLAwfOQoLrA=='},function(ret, err) {
if (ret.status == 'success') api.toast({ msg: ret.result.userId });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
disconnect
断开连接
disconnect({params}, callback(ret, err))
params
isReceivePush:
- 类型:布尔
- 默认值:true
- 描述:断开后是否接收 Push
callback(ret)
ret:
- 类型:JSON 对象
- 描述:返回的断开连接成功或者失败的状态
- 内部字段:
{
status: 'success' // 状态码:success
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.disconnect({
isReceivePush: true
}, function(ret, err) {
if ('success' == ret.status) {
api.toast({ msg: '断开连接成功!' });
}
}); // 断开,且不再接收 Push
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setConnectionStatusListener
设置连接状态变化的监听器,请在调用 init 方法之后,调用 connect 方法之前设置
setConnectionStatusListener(callback(ret, err))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:连接服务器的回调返回值,参见 连接状态
- 内部字段:
{
result:
{
connectionStatus: 'CONNECTED' // 连接状态
}
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 的代码省略
rong.setConnectionStatusListener(function(ret, err) {
api.toast({ msg: ret.result.connectionStatus });
});
// 之后调用 connect 的代码省略
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendTextMessage
发送文字消息
sendTextMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
text:
- 类型:字符串
- 默认值:无
- 描述:消息的文字内容
extra:
- 类型:字符串
- 默认值:无
- 描述:消息的附加信息
mentionedInfo:
- 类型:JSON类型
- 默认值:无 (可选)
- 描述:@功能,当conversationType为GROUP或DISCUSSION有效;(ios不支持DISCUSSION);注:@ 消息推送会越过所有免打扰逻辑,给用户推送 Push 通知。
- 内部字段:
type:"all" //(可选项) 字符串类型;@消息类型,默认值:all;取值范围:(all,part);all为@群组里所有人;part为@部分人,
userIdList:['123'] //字符串类型的数组;用户id;当type为part时,需要填写此字段;
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / success / error
result:
{
message:
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '',
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
成功:
{
status: 'success', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendTextMessage({
conversationType: 'PRIVATE',
targetId: '9527',
text: 'Hello world.',
extra: ''
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendVoiceMessage
发送语音消息
sendVoiceMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
voicePath:
- 类型:字符串
- 默认值:无
- 描述:语音文件的路径,支持 fs://,如:fs:///voice/123.amr。文件要求为 AMR 格式
duration:
- 类型:数字
- 默认值:无
- 描述:语音消息的时长,单位为秒
extra:
- 类型:字符串
- 默认值:无
- 描述:消息的附加信息
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / success / error
result:
{
message:
{
content: {
voicePath: '/xxx/xxx/voice.amr',
duration: 5,
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:VcMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
成功:
{
status: 'success', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendVoiceMessage({
conversationType: 'PRIVATE',
targetId: '9527',
voicePath: 'fs:///xxx/xxx/voice.amr',
duration: 5,
extra: ''
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendImageMessage
发送图片消息
sendImageMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
imagePath:
- 类型:字符串
- 默认值:无
- 描述:图片的路径,支持 fs://,如:fs:///image/123.jpg
extra:
- 类型:字符串
- 默认值:无
- 描述:消息的附加信息
isFull:
- 类型:布尔类型
- 描述:是否发送原图
- 默认值:false
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / progress / success / error
result:
{
message:
{
content: {
imageUrl: '/xxx/xxx/image.jpg',
thumbPath: '/xxx/xxx/thumb.jpg',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:ImgMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
发送中:
{
status: 'progress', // 状态码:prepare / progress / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
},
progress: 66 // 发送进度
}
}
成功:
{
status: 'success', // 状态码:prepare / progress / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / progress / success / error
result:
{
message:
{
sentStatus: 'FAILED', // 发送状态:SENDING, SENT 或 FAILED
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendImageMessage({
conversationType: 'PRIVATE',
targetId: '9527',
imagePath: 'fs:///xxx/xxx/picture.jpg',
extra: ''
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'progress')
api.toast({ msg: ret.result.progress });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendRichContentMessage
发送图文消息
sendRichContentMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
title:
- 类型:字符串
- 默认值:无
- 描述:消息的标题
description:
- 类型:字符串
- 默认值:无
- 描述:消息的内容描述
imageUrl:
- 类型:字符串
- 默认值:无
- 描述:消息图片的网络地址
extra:
- 类型:字符串
- 默认值:无
- 描述:消息的附加信息
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / success / error
result:
{
message:
{
content: {
title: 'Big News',
description: 'I am Ironman.',
imageUrl: 'http://p1.cdn.com/fds78ruhi.jpg',
extra: '',
url: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:ImgTextMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
成功:
{
status: 'success', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / success / error
result:
{
message:
{
sentStatus: 'FAILED', // 发送状态:SENDING, SENT 或 FAILED
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendRichContentMessage({
conversationType: 'PRIVATE',
targetId: '9527',
title: 'Big News',
description: 'I am Ironman.'
imageUrl: 'http://ironman.com/xxx/xxx/picture.jpg',
extra: ''
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendLocationMessage
发送位置消息
sendLocationMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
latitude:
- 类型:数字
- 默认值:无
- 描述:消息的文字内容
longitude:
- 类型:数字
- 默认值:无
- 描述:消息的文字内容
poi:
- 类型:字符串
- 默认值:无
- 描述:消息的文字内容
imagePath:
- 类型:字符串
- 默认值:无
- 描述:地图缩率图的路径,支持 fs://,如:fs:///location_thumb/123.jpg
extra:
- 类型:字符串
- 默认值:无
- 描述:消息的附加信息
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / progress / success / error
result:
{
message:
{
content: {
latitude: 39.9139
longitude: 116.3917
poi: '北京市朝阳区北苑路北辰泰岳大厦',
imagePath: '/xxx/xxx/location.jpg'
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:LBSMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
发送中:
{
status: 'progress', // 状态码:prepare / progress / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
},
progress: 66 // 发送进度
}
}
成功:
{
status: 'success', // 状态码:prepare / progress / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / progress / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendLocationMessage({
conversationType: 'PRIVATE',
targetId: '9527',
latitude: 39.9139,
longitude: 116.3917,
poi: '北京市朝阳区北苑路北辰泰岳大厦',
imagePath: 'fs:///xxx/xxx/location.jpg',
extra: ''
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'progress')
api.toast({ msg: ret.result.progress });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendCommandNotificationMessage
发送命令消息,可以用来实现任何自定义消息的发送
sendCommandNotificationMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
name:
- 类型:字符串
- 默认值:无
- 描述:命令的名称
data:
- 类型:字符串
- 默认值:无
- 描述:命令的数据
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / success / error
result:
{
message:
{
content: {
name: 'AddFriend',
data: '{\"inviteUserId\":123}'
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
成功:
{
status: 'success', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendCommandNotificationMessage({
conversationType: 'PRIVATE',
targetId: '9527',
name: 'AddFriend',
data: '{\"inviteUserId\":123}'
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendCommandMessage
发送命令消息,您需要这种类型的消息时可以直接使用,不需要再自定义。此消息不保存、不计数。
sendCommandMessage({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 默认值:无
- 描述:消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
targetId:
- 类型:字符串
- 默认值:无
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
name:
- 类型:字符串
- 默认值:无
- 描述:命令的名称
data:
- 类型:字符串
- 默认值:无
- 描述:命令的数据
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的消息内容。发送准备时,提供所有消息信息;之后,result 中将只返回 message.messageId 等必要相关的内容
- 内部字段:
发送准备:
{
status: 'prepare', // 状态码:prepare / success / error
result:
{
message:
{
content: {
name: 'AddFriend',
data: '{\"inviteUserId\":123}'
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '16', // 接收者 Id
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0 // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
messageUId: '' //消息UID,如果无则显示空字符串
}
}
}
成功:
{
status: 'success', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
失败:
{
status: 'error', // 状态码:prepare / success / error
result:
{
message:
{
messageId: 608 // 本地消息 Id
}
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30014 | 发送处理失败 |
30003 | 服务器超时 |
31009 | 用户被屏蔽 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
405 | 用户在黑名单中 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendCommandMessage({
conversationType: 'PRIVATE',
targetId: '9527',
name: 'AddFriend',
data: '{\"inviteUserId\":123}'
}, function(ret, err) {
if (ret.status == 'prepare')
api.toast({ msg: JSON.stringify(ret.result.message) });
else if (ret.status == 'success')
api.toast({ msg: ret.result.message.messageId });
else if (ret.status == 'error')
api.toast({ msg: err.code });
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setOnReceiveMessageListener
设置接收消息的监听器,请在调用 init 方法之后,调用 connect 方法之前设置
所有接收到的消息、通知、状态都经由此处设置的监听器处理。包括私聊消息、讨论组消息、群组消息、聊天室消息以及各种其他消息、通知、状态等
setOnReceiveMessageListener(callback(ret, err))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:接收到的消息内容和剩余消息条数
- 内部字段:
{
result: {
message:{
content: { //JSON对象;消息内容
text: 'Hello world!',
extra: ''
},
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
},
left: 0 // 剩余未拉取的消息数目
},
isPushMsg: false //布尔类型;是否是推送消息,本参数仅在iOS平台有效。
//在 iOS 平台上APP收到推送时,有以下几种情况:
//1,应用在前台激活状态,开发者可同本接口获取推送消息,此时 result数据格式如下文说明
//2,应用在后台但未被杀死,此时系统弹出推送提示。若用户点击推送提示,开发者可同本接口获取推送消息,此时 result数据格式如下文说明。若用户不点击推送提示,直接点击app进入应用,则获取
//3,应用未激活,此时收到推送后,系统会弹出提示框,用户点击该提示框,开发者可通过api对象下noticeclicked事件监听到推送消息。
//注意:如果用户不点击推送提示框,而是直接点击app图标进入应用,开发者是收不到推送消息的。
}
档 isPushMsg 为 true 时 result 数据的格式说明:
{
_j_msgid:20266200178825380, //数字类型;
infoid:'0', //字符串类型;
_j_business:1, //数字类型;
id:62358', //字符串类型;
aps:{ //JSON对象
sound:'default', //字符串类型;
badge:1, //数字类型;
alert:'你有新的消息' //字符串类型;
},
_j_uid:12108421449, //数字类型;
type:‘8’, //字符串类型;
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 的代码省略
rong.setOnReceiveMessageListener(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result.message) });
api.toast({ msg: ret.result.message.left });
})
// 之后调用 connect 的代码省略
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getOfflineMessageDuration
获取当前用户离线消息时间
getOfflineMessageDuration(callback(ret, err))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:获取状态
- 内部字段:
status: true //布尔类型;获取到的状态
duration: '' //字符串类型;当前用户离线消息时间,单位:天
err:
- 类型:JSON 对象
- 描述:获取状态
- 内部字段:
errCode: '' //数字类型;错误码;详情参见:https://www.rongcloud.cn/docs/status_code.html#android_ios_code
示例代码
var rong = api.require('rongCloudIM');
rong.getOfflineMessageDuration(function(ret, err) {
api.toast({ msg: JSON.stringify(ret) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setOfflineMessageDuration
设置当前用户离线消息存储时间
setOfflineMessageDuration(params, callback(ret, err))
params
duration:
- 类型:数字类型
- 描述:(可选项)用户离线消息存储时间(以天为单位),范围【1~7天】
- 默认值:1
callback(ret)
ret:
- 类型:JSON 对象
- 描述:获取状态
- 内部字段:
status: true //布尔类型;获取到的状态
time: '' //字符串类型;设置成功后的时间(毫秒值)(iOS不支持)
err:
- 类型:JSON 对象
- 描述:获取状态
- 内部字段:
errCode: '' //数字类型;错误码;详情参见:https://www.rongcloud.cn/docs/status_code.html#android_ios_code
示例代码
var rong = api.require('rongCloudIM');
rong.setOfflineMessageDuration({duration:2}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
searchConversations
搜索本地历史消息
searchConversations({params}, callback(ret))
params
conversationTypes:
- 类型:数组类型
- 描述:搜索的会话类型,参见 会话类型
objectNames:
- 类型:数组类型
- 描述:搜索的消息类型。比如:RC:TxtMsg;详情参见:http://docs.rongcloud.cn/android_message.html#_内置内容类消息
keyword:
- 类型:字符串类型
- 描述: 搜索的关键字
callback(ret)
ret:
- 类型:JSON 对象
- 描述:会话信息
- 内部字段:
{
status: 'success',
result: [
{
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
receivedStatus: 'READ', // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.searchConversations({
conversationTypes: ['PRIVATE'],
objectNames: ['RC:TxtMsg'],
keyword:'hello'
}, function(ret) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
searchMessages
根据会话,搜索本地历史消息。
searchMessages({params}, callback(ret))
params
conversationType:
- 类型:字符串类型
- 描述:指定的会话类型,参见 会话类型
targetId:
- 类型:字符串类型
- 描述:指定的会话 id
keyword:
- 类型:字符串类型
- 描述: 搜索的关键字
count:
- 类型:数字类型
- 描述: 返回的搜索结果数量(iOS平台为返回的最大搜索结果数量), 安卓平台传0时会返回所有搜索到的消息, 非0时,逐页返回
- 默认值:0
beginTime:
- 类型:数字类型
- 描述: 查询记录的起始时间, 传0时从最新消息开始搜索。(单位:毫秒值)
- 默认值:0
callback(ret)
ret:
- 类型:JSON 对象
- 描述:会话信息
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 参见 发送出的消息状态
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.searchMessages({
conversationType: 'PRIVATE',
targetId: '1234',
keyword:'hello'
}, function(ret) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getConversationList
获取会话列表
会话列表按照时间从前往后排列,如果有置顶会话,则置顶会话在前
getConversationList(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:会话列表
- 内部字段:
{
status: 'success',
result: [
{
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
receivedStatus: 'READ', // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id,
mentionedCount: 2 //本会话里自己被@的消息数量(iOS不支持)
hasUnreadMentioned:true //会话中是否存在被@的消息,在清除会话未读数的时候,会将此状态置成false(android不支持)
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getConversationList(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getTopConversationList
获取置顶会话列表
getTopConversationList(callback(ret))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:会话列表
- 内部字段:
{
status: 'success',
result: [
{
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
receivedStatus: 'READ', // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id,
mentionedCount: 2 //本会话里自己被@的消息数量(iOS不支持)
hasUnreadMentioned:true //会话中是否存在被@的消息,在清除会话未读数的时候,会将此状态置成false(android不支持)
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getTopConversationList(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getBlockedConversationList
获取屏蔽消息的会话列表
getBlockedConversationList(params, callback(ret))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见会话类型(ios不支持)
- 默认值:PRIVATE
callback(ret)
ret:
- 类型:JSON 对象
- 描述:会话列表
- 内部字段:
{
status: 'success',
result: [
{
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
receivedStatus: 'READ', // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id,
mentionedCount: 2 //本会话里自己被@的消息数量(iOS不支持)
hasUnreadMentioned:true //会话中是否存在被@的消息,在清除会话未读数的时候,会将此状态置成false(android不支持)
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getBlockedConversationList(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getConversationListByCount
分页获取会话列表
会话列表按照时间从前往后排列,如果有置顶会话,则置顶会话在前
getConversationListByCount({params},callback(ret, err))
params
typeList:
- 类型:数组
- 描述:(可选项)回话类型组成的数组
- 默认值:['private','group','discussion','system']
- 取值范围:
- private:单聊
- discussion:讨论组
- group:群组
- chatroom:聊天室
- customerService:客服
- system:系统会话
- appService:应用内公众服务会话
- publicService:跨应用公众服务会话
- pushService:推送服务会话
count:
- 类型:数字
- 描述:(可选项)获取的数量
- 默认:10
startTime:
- 类型:数字
- 描述:(可选项)会话的时间戳(获取这个时间戳之前的会话列表,0表示从最新开始获取)
- 默认:0
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:会话列表
- 内部字段:
{
status: 'success',
result: [
{
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
receivedStatus: 'READ', // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id,
mentionedCount: 2 //本会话里自己被@的消息数量(iOS不支持)
hasUnreadMentioned:true //会话中是否存在被@的消息,在清除会话未读数的时候,会将此状态置成false(android不支持)
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getConversationListByCount(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getConversation
获取某一会话信息
getConversation({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:会话信息
- 内部字段:
{
status: 'success',
result: {
conversationTitle: 'Ironman', // 会话标题
conversationType: 'PRIVATE', // 参见 会话类型 枚举
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
draft: '', // 文字消息草稿的内容
targetId: 'group001', // 消息目标 Id
latestMessage: {
text: 'Hello world!',
extra: ''
}, // 最后一条消息的内容
sentStatus: 'SENT', // 参见 发送出的消息状态
*notificationStatus: 'NOTIFY', // 会话通知状态,2.0将不再提供此字段,可通过 getConversationNotificationStatus 获取
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
recievedStatus: 0, // 参见 接收到的消息状态
senderUserId: '55', // 发送消息的用户 Id
unreadMessageCount: 10, // 本会话的未读消息数
receivedTime: 1418968547905, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
sentTime: 1418968488063, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
isTop: false, // 置顶状态
latestMessageId: 608 // 本会话最后一条消息 Id,
mentionedCount: 2 //本会话里自己被@的消息数量(iOS不支持)
hasUnreadMentioned:true //会话中是否存在被@的消息,在清除会话未读数的时候,会将此状态置成false(android不支持)
}
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getConversation({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getMessageCount
获取某一会话信息数量
getMessageCount({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:会话信息
- 内部字段:
{
status: 'success',
result: {
count: // 数字类型;当前会话消息数
}
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getMessageCount({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS系统
可提供的 1.0.0 及更高版本
removeConversation
从会话列表中移除某一会话,但是不删除会话内的消息
如果此会话中有新的消息,该会话将重新在会话列表中显示,并显示最近的历史消息
removeConversation({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.removeConversation({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
clearConversations
清空所有会话及会话消息
clearConversations({params}, callback(ret, err))
params
conversationTypes:
- 类型:字符串数组
- 默认值:无
- 描述:消息的会话类型,参见 会话类型
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.clearConversations({
conversationTypes: ['PRIVATE', 'GROUP']
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setConversationToTop
设置某一会话为置顶或者取消置顶
setConversationToTop({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
isTop:
- 类型:布尔
- 描述:是否置顶
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setConversationToTop({
conversationType: 'PRIVATE',
targetId: '9527',
isTop: true
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getConversationNotificationStatus
获取某一会话的通知状态
getConversationNotificationStatus({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: {
code: 0 // 状态码,0:免打扰 / 1:提醒
notificationStatus: 'DO_NOT_DISTURB' // 参见 会话通知提醒状态 枚举
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getConversationNotificationStatus({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: ret.result.code });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setConversationNotificationStatus
设置某一会话的通知状态
setConversationNotificationStatus({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
notificationStatus:
- 类型:字符串
- 描述:会话通知提醒状态,参见 会话通知提醒状态
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: {
code: 0 // 状态码,0:免打扰 / 1:提醒
notificationStatus: "DO_NOT_DISTURB" // 参见 会话通知提醒状态 枚举
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
300003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setConversationNotificationStatus({
conversationType: 'PRIVATE',
targetId: '9527',
notificationStatus: 'DO_NOT_DISTURB'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: ret.result.code });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getLatestMessages
获取某一会话的最新消息记录
getLatestMessages({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
count:
- 类型:数字
- 描述:要获取的消息数量
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:最新消息记录,按照时间顺序从新到旧排列。
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 参见 发送出的消息状态
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getLatestMessages({
conversationType: 'PRIVATE',
targetId: '9527',
count: 20
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getHistoryMessages
获取某一会话的历史消息记录
getHistoryMessages({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
oldestMessageId:
- 类型:数字
- 描述:最后一条消息的 Id,获取此消息之前的 count 条消息,没有消息第一次调用应设置为: -1
count:
- 类型:数字
- 描述:要获取的消息数量
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:最新消息记录,按照时间顺序从新到旧排列。
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 参见 发送出的消息状态
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getHistoryMessages({
conversationType: 'PRIVATE',
targetId: '9527',
oldestMessageId: 688,
count: 20
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getUnreadMentionedMessages
获取某会话里未读的@消息。
getUnreadMentionedMessages({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:未读的@消息。
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 参见 发送出的消息状态
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getUnreadMentionedMessages({
conversationType: 'GROUP',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 3.1.4 及更高版本
getHistoryMessagesByObjectName
按照消息类型获取历史消息记录
getHistoryMessagesByObjectName({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
objectName:
- 类型:字符串
- 描述:消息类型标识
oldestMessageId:
- 类型:数字
- 描述:最后一条消息的 Id,获取此消息之前的 count 条消息,没有消息第一次调用应设置为: -1
count:
- 类型:数字
- 描述:要获取的消息数量
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:最新消息记录,按照时间顺序从新到旧排列。
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 参见 发送出的消息状态
senderUserId: '55', // 发送者 userId
messageId: 608, // 本地消息 Id
sentTime: 1418971531533, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 0, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
messageUId: '' //消息UID,如果无则显示空字符串
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getHistoryMessagesByObjectName({
conversationType: 'PRIVATE',
targetId: '9527',
objectName: 'RC:TxtMsg',
oldestMessageId: 688,
count: 20
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
deleteMessages
删除指定的一条或者一组消息
deleteMessages({params}, callback(ret, err))
params
messageIds:
- 类型:数字数组
- 描述:要删除的消息 Id 数组
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.deleteMessages({
messageIds: [688, 689]
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
clearMessages
清空某一会话的所有聊天消息记录
clearMessages({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.clearMessages({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
recallMessage
撤回消息
recallMessage({params}, callback(ret, err))
params
messageId:
- 类型:字符串
- 描述:消息ID
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
success: true // 布尔类型;是否成功
messageId: 888 // 数值类型;撤回的消息ID,该消息已经变更为新的消息;(android不支持)
operatorId: '' //字符串类型;发起撤回消息的用户id;(ios不支持)
recallTime: //数值类型; 撤回的时间(毫秒)(ios不支持)
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 1, // 数值类型;错误code
}
示例代码
var rong = api.require('rongCloudIM');
rong.recallMessage({
messageId : 888
}, function(ret, err){
if (ret.success) {
alert(JSON.stringify(ret));
}else {
alert(JSON.stringify(err));
}
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setOnMessageRecalledListener
监听撤回消息
setOnMessageRecalledListener(callback(ret))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
messageId: 888 // 数值类型;被撤回的消息ID
}
示例代码
var rong = api.require('rongCloudIM');
rong.setOnMessageRecalledListener(function(ret){
alert(JSON.stringify(ret));
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getTotalUnreadCount
获取所有未读消息数
getTotalUnreadCount(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success',
result: 12 // 未读消息数
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getTotalUnreadCount(function(ret, err) {
api.toast({ msg: ret.result });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getUnreadCount
获取来自某用户(某会话)的未读消息数
getUnreadCount({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success',
result: 12 // 未读消息数
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getUnreadCount({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.result });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getUnreadCountByConversationTypes
获取某(些)会话类型的未读消息数
getUnreadCountByConversationTypes({params}, callback(ret, err))
params
conversationTypes:
- 类型:字符串数组
- 描述:消息的会话类型,参见 会话类型
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success',
result: 12 // 未读消息数
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getUnreadCountByConversationTypes({
conversationTypes: ['PRIVATE', 'GROUP']
}, function(ret, err) {
api.toast({ msg: ret.result });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setMessageReceivedStatus
设置接收到的消息状态
setMessageReceivedStatus({params}, callback(ret, err))
params
messageId:
- 类型:数字
- 描述:消息 Id
receivedStatus:
- 类型:字符串
- 描述:设置接收到的消息状态,参见 接收到的消息状态
- 特别说明:此参数在1.0版本中为数字类型,在2.0版本中统一了消息状态,变更为字符串类型
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setMessageReceivedStatus({
messageId: '688',
receivedStatus: 'READ'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
clearMessagesUnreadStatus
清除某一会话的消息未读状态
clearMessagesUnreadStatus({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.clearMessagesUnreadStatus({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setMessageExtra
设置消息的附加信息,此信息只保存在本地
setMessageExtra({params}, callback(ret, err))
params
messageId:
- 类型:数字
- 描述:消息 Id
value:
- 类型:字符串
- 描述:消息附加信息,最大 1024 字节
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setMessageExtra({
messageId: '688',
value: 'extra info'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getTextMessageDraft
获取某一会话的文字消息草稿
getTextMessageDraft({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success',
result: 'Hello w' // 草稿的文字内容
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getTextMessageDraft({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.result });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
saveTextMessageDraft
保存某一会话的文字消息草稿
saveTextMessageDraft({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
content:
- 类型:字符串
- 描述:草稿的文字内容
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.saveTextMessageDraft({
conversationType: 'PRIVATE',
targetId: '9527',
content: 'Hello w'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
clearTextMessageDraft
清除某一会话的文字消息草稿
clearTextMessageDraft({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.clearTextMessageDraft({
conversationType: 'PRIVATE',
targetId: '9527'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
createDiscussion
创建讨论组
createDiscussion({params}, callback(ret, err))
params
name:
- 类型:字符串
- 描述:讨论组名称,如:当前所有成员的名字的组合。
userIdList:
- 类型:字符串数组
- 描述:讨论组成员 Id 列表
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: {
discussionId: "1b9f7abe-a5ae-463d-8ff8-d96deaf40b59" // 创建成功的讨论组 Id
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.createDiscussion({
name: 'Ironman, Batman',
userIdList: ['1234', '4321']
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: ret.result.discussionId });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getDiscussion
获取讨论组信息和设置
getDiscussion({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 描述:讨论组 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: {
creatorId: '55', // 讨论组创建者 Id
id: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59', //讨论组 Id
name: 'Ironman, Batman', // 讨论组名称
memberIdList: [ '1234', '4321' ], // 成员 Id 列表
inviteStatus: 'OPENED' // 是否公开好友邀请:OPENED / CLOSED,参见 讨论组邀请状态
}
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getDiscussion({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.result.discussion) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setDiscussionName
设置讨论组名称
setDiscussionName({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 描述:讨论组 Id
name:
- 类型:字符串
- 默认值:无
- 描述:讨论组名称
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setDiscussionName({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59',
name: 'Ironman, Hulk'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
addMemberToDiscussion
添加一名或者一组用户加入讨论组
addMemberToDiscussion({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 描述:讨论组 Id
userIdList:
- 类型:字符串数组
- 描述:邀请的用户 Id 列表
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.addMemberToDiscussion({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59',
userIdList: ['4567', '7654']
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
removeMemberFromDiscussion
供创建者将某用户移出讨论组
移出自己或者调用者非讨论组创建者将产生 -1 未知错误
removeMemberFromDiscussion({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 描述:讨论组 Id
userId:
- 类型:字符串
- 描述:用户 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.removeMemberFromDiscussion({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59',
userId: '4567'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
quitDiscussion
退出当前用户所在的某讨论组
quitDiscussion({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 默认值:无
- 描述:讨论组 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.quitDiscussion({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setDiscussionInviteStatus
设置讨论组成员邀请权限
setDiscussionInviteStatus({params}, callback(ret, err))
params
discussionId:
- 类型:字符串
- 描述:讨论组 Id
inviteStatus:
- 类型:字符串
- 描述:邀请状态,默认为开放,参见 讨论组邀请状态
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setDiscussionInviteStatus({
discussionId: '1b9f7abe-a5ae-463d-8ff8-d96deaf40b59',
inviteStatus: 'OPENED'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
joinChatRoom
当前用户加入某聊天室
joinChatRoom({params}, callback(ret, err))
params
chatRoomId:
- 类型:字符串
- 描述:聊天室 Id
defMessageCount:
- 类型:数字
- 描述:进入聊天室拉取消息数目
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.joinChatRoom({
chatRoomId: '123',
defMessageCount: 20
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
quitChatRoom
当前用户退出某聊天室
quitChatRoom({params}, callback(ret, err))
params
chatRoomId:
- 类型:字符串
- 描述:聊天室 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
err:
- 类型:JSON 对象
- 内部字段:
{
code: 30003
}
状态码说明:
状态码 | 说明 |
---|---|
30003 | 服务器超时 |
-10000 | 未调用 init 方法进行初始化 |
-10001 | 未调用 connect 方法进行连接 |
-10002 | 输入参数错误 |
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.quitChatRoom({
chatRoomId: '123'
}, function(ret, err) {
if (ret.status == 'success')
api.toast({ msg: JSON.stringify(ret.status) });
else
api.toast({ msg: err.code });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getConnectionStatus
获取连接状态
getConnectionStatus(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:连接状态枚举,参见 连接状态;
- 内部字段:
{
status: 'success',
result:
{
connectionStatus: 'CONNECTED' // 连接状态
}
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getConnectionStatus(function(ret, err) {
api.toast({ msg: ret.result.connectionStatus });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
logout
注销登录(不再接收 Push 消息)
logout(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:返回的注销登录成功或者失败的状态
- 内部字段:
{
status: 'success' // 状态码:success
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.logout(function(ret, err) {
if (ret.status == 'error')
api.toast({ msg: err.code });
}); // 断开,且不再接收 Push
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getRemoteHistoryMessages
获取历史消息记录(特别说明:调用此方法需要开启历史消息漫游;当用户因换设备或重装app导致本地本地存储丢失的情况,可用此方法获取记录;此方法返回值中messageId均为0,融云服务器不会保存此值)
此方法从服务器端获取之前的历史消息,但是必须先开通历史消息云存储功能。 例如,本地会话中有10条消息,您想拉取更多保存在服务器的消息的话,recordTime应传入最早的消息的发送时间戳,count传入1~20之间的数值。
getRemoteHistoryMessages({params}, callback(ret, err))
params
conversationType:
- 类型:字符串
- 描述:消息的会话类型,参见 会话类型;不支持传入 RCConversationType.CHATROOM。
targetId:
- 类型:字符串
- 描述:目标 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
dateTime :
- 类型:日期
- 描述:从该时间点开始获取消息。即:消息中的 sentTime;第一次可传 0,再次取值此参数可传入上一次获取的最后一条记录的sentTime值。
count:
- 类型:数字
- 描述:要获取的消息数量(1-20条)
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:最新消息记录,按照时间顺序从新到旧排列。
- 内部字段:
{
status: 'success',
result: [
{
content: {
text: 'Hello world!',
extra: ''
}, // 消息内容
readReceiptInfo:{ // 注:如果此字段无值,则返回空
hasRespond:true, //是否已经发送回执
isReceiptRequestMessage:true,//是否需要回执消息
userIdList:{}, //发送回执的用户ID列表 (android不支持)
userIds:[] //json数组类型;发送回执的用户ID和时间戳列表 (ios不支持)
},
extra: '', // 消息的附加信息,此信息只保存在本地
conversationType: 'PRIVATE', // 参见 会话类型 枚举
messageDirection: 'SEND', // 消息方向:SEND 或者 RECEIVE
targetId: '55', // 这里对应消息发送者的 userId
objectName: 'RC:TxtMsg', // 消息类型,参见 http://docs.rongcloud.cn/android_message.html#_内置内容类消息
sentStatus: 'SENDING', // 发送状态:SENDING, SENT 或 FAILED
senderUserId: '55', // 发送者 userId
messageId: 0, // 融云服务器不保存此值,返回值均为0
sentTime: 1444446587902, // 发送消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedTime: 1444446598989, // 收到消息的时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数
receivedStatus: 'LISTENED' // 消息状态(android不支持) 取值范围:UNREAD,READ,LISTENED,DOWNLOADED,RETRIEVED,MULTIPLERECEIVE
isRead:true, //获取是否已读取的状态(ios不支持)
isListened:true, //获取是否已被收听的状态(ios不支持)
isDownload:true, //获取文件是否已经下载的状态(ios不支持)
isRetrieved:false, //获取是否已经被收取过(ios不支持)
isMultipleReceive: false //获取是否被其他端同时接收(ios不支持)
}
]
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getRemoteHistoryMessages({
conversationType: 'PRIVATE',
targetId: '9527',
dateTime: 1418971531533,
count: 20
}, function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
addToBlacklist
将某个用户加到黑名单中
addToBlacklist({params}, callback(ret, err))
params
userId:
- 类型:字符串
- 描述:要加入黑名单的用户 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.addToBlacklist({
userId: '688'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
removeFromBlacklist
将个某用户从黑名单中移出
removeFromBlacklist({params}, callback(ret, err))
params
userId:
- 类型:字符串
- 描述:要移出黑名单的用户 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.removeFromBlacklist({
userId: '688'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getBlacklistStatus
获取某用户是否在黑名单中
getBlacklistStatus({params}, callback(ret, err))
params
userId:
- 类型:字符串
- 描述:要查询的用户 Id
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: 1 // 1-不在黑名单;0-在黑名单
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getBlacklistStatus({
userId: '688'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getBlacklist
获取当前用户的黑名单列表
getBlacklist(callback(ret))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' ,// 状态码:success / error
result: ['aaa','bbb']
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getBlacklist(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setNotificationQuietHours
设置消息通知免打扰时间,此方法会屏蔽该会话在该时间段的远程推送;
setNotificationQuietHours({params}, callback(ret, err))
params
startTime:
- 类型:字符串
- 描述:起始时间 格式 HH:MM:SS
spanMinutes :
- 类型:数字
- 描述:间隔分钟数 0 < spanMinutes < 1440。
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setNotificationQuietHours({
startTime: '22:00:00',
spanMinutes: 6
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
removeNotificationQuietHours
移除消息通知免打扰时间
removeNotificationQuietHours(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.removeNotificationQuietHours(function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getNotificationQuietHours
获取消息通知免打扰时间
getNotificationQuietHours(callback(ret))
callback(ret)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' , // 状态码:success / error
result: {
startTime: "22:00:00", // 起始时间
spanMinutes: 6 // 间隔分钟数
}
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getNotificationQuietHours(function(ret, err) {
api.toast({ msg: JSON.stringify(ret.result) });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
setMessageSentStatus
设置消息发送状态
setMessageSentStatus({params}, callback(ret, err))
params
messageId:
- 类型:数字
- 描述:消息 Id
sentStatus :
- 类型:字符串
- 描述:发送出的消息的状态枚举,参见 发送状态;
callback(ret)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.setMessageSentStatus({
messageId: 8,
sentStatus: 'READ'
}, function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendTypingStatus
向会话中发送正在输入的状态。
注意:在 6 秒之内,如果同一个用户在同一个会话中多次调用此接口发送正在输入的状态,为保证产品体验和网络优化,将只有最开始的一次生效。目前本接口仅支持单聊。
sendTypingStatus({params})
params
conversationType:
- 类型:字符串
- 描述:(可选项)消息的会话类型,通过改变消息会话类型,可以发送单聊消息、讨论组消息、群聊消息、聊天室消息等,参见 会话类型
- 默认值:PRIVATE
targetId:
- 类型:字符串
- 描述:消息的接收方 Id。根据不同的 conversationType,可能是用户 Id、讨论组 Id、群组 Id 或聊天室 Id 等
objectName:
- 类型:字符串
- 描述:正在输入的消息的类型名,如文本消息,应该传类型名"RC:TxtMsg"。会话中的其他用户输入状态回执中会收到此消息类型,可以通过此消息类型,自定义不同的输入状态提示(如:正在输入、正在讲话、正在拍摄等)。
- 取值范围:
- RC:TxtMsg 文本消息
- RC:VcMsg 语音类型
- RC:ImgMsg 图片类型
- 默认值:无
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendTypingStatus({
conversationType: 'PRIVATE',
targetId: '9527',
objectName: 'RC:TxtMsg'
});
可用性
iOS 系统,Android 系统
可提供的 3.0.6 及更高版本
addTypingStatusListener
监听对方输入状态
addTypingStatusListener(callback(ret))
callback(ret)
ret:
- 类型:JSON对象
- 描述:正在输入的信息
- 内部字段:
{
conversationType: , //字符串类型;会话类型
targetId: , //字符串类型;会话目标ID
userTypingStatusList:[] //数字类型;正在输入的用户列表
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.addTypingStatusListener(function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 3.0.6 及更高版本
sendReadReceiptResponse
如果在会话中收到了回执请求,接收者需要在合适的时机响应该请求,以通知发送者自己已经阅读了该消息。
sendReadReceiptResponse(params, callback(ret))
params
conversationType:
- 类型:字符串类型
- 描述:会话类型
- 默认值:GROUP
targetId:
- 类型:字符串类型
- 描述:targetId
messageId:
- 类型:数字类型
- 描述:消息id
callback(ret)
ret:
- 类型:JSON对象
- 描述:设置后状态
- 内部字段:
{
status: , //布尔类型;状态
errorCode: , //数字;错误码;status为false时有值
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendReadReceiptResponse({messageId:1,targetId:"2er"}, function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendReadReceiptMessage
发送单聊中消息已读的回执
sendReadReceiptMessage(params, callback(ret))
params
targetId:
- 类型:字符串
- 描述:目标会话ID
timestamp:
- 类型:数字
- 描述:该会话中已阅读的最后一条消息的发送时间戳
callback(ret)
ret:
- 类型:JSON对象
- 描述:设置后状态
- 内部字段:
{
status: , //布尔类型;状态
errorCode: , //数字;错误码;status为false时有值
}
示例代码
var rong = api.require('rongCloudIM');
rong.sendReadReceiptMessage({targetId:1}, function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
addReceiveReadReceiptListener
添加收到已读回执的监听
addReadReceiptListener(callback(ret))
callback(ret)
ret:
- 类型:JSON对象
- 描述:收到这个消息之后可以更新这个会话中 messageTime 以前的消息 UI 为已读(底层数据库消息状态已经改为已读)。
- 内部字段:
{
tId: //字符串类型;会话 id
messageTime: //数字类型;已阅读的最后一条消息的 sendTime
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.addReceiveReadReceiptListener(function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
sendReadReceiptRequest
发起群组消息回执请求。只能对自己发送的消息发起消息回执请求。
此功能目前仅在 GROUP 类型的会话中开放。用户可以对自己发送的消息发起阅读回执请求,发起后可以看到有多少人阅读过这条消息。
sendReadReceiptRequest(params, callback(ret))
params
messageId:
- 类型:数字类型
- 描述:消息id
callback(ret)
ret:
- 类型:JSON对象
- 描述:设置后状态
- 内部字段:
{
status: , //布尔类型;状态
errorCode: , //数字;错误码;status为false时有值
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.sendReadReceiptRequest({messageId:1}, function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
addReadReceiptListener
添加消息回执监听
您需要设置消息回执监听,以此来接收回执消息并更新消息的显示。
addReadReceiptListener(params, callback(ret))
params
target:
- 类型:字符串类型
- 描述:要监听的事件
- 默认:onMessageReceiptResponse
- 取值范围:
- onMessageReceiptResponse:在群组中发起了回执请求的用户,当收到接收方的响应时,会回调此方法。
- onMessageReceiptRequest:群组中,某人发起了回执请求,会话中其余人会收到该请求,并回调此方法。 接收方需要在合适的时机(读取了消息之后)调用sendReadReceiptResponse回复响应
callback(ret)
ret:
- 类型:JSON对象
- 描述:设置后状态
- 内部字段:
{
conversationType: //字符串类型;会话类型;
targetId: //字符串类型;会话 id
messageUId: //字符串类型;当target为onMessageReceiptResponse表示收到回执响应的消息的 uId,当target为onMessageReceiptRequest表示请求已读回执的消息 uId
respondUserIdList: //数组类型;当target为onMessageReceiptResponse时有值;会话中响应了此消息的用户列表;其内部为JSON类型,其中 userId: 用户 id ; time: 响应时间
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.addReadReceiptListener(function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
removeReadReceiptListener
移除消息回执监听
removeReadReceiptListener(params)
params
target:
- 类型:字符串类型
- 描述:要监听的事件
- 默认:onMessageReceiptResponse
- 取值范围:
- onMessageReceiptResponse
- onMessageReceiptRequest
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.removeReadReceiptListener(function(ret){
api.alert({msg:JSON.stringify(ret)});
});
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
getCurrentUserId
获取当前连接用户的信息
getCurrentUserId(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success', // 状态码:success / error
result: 'apple' // 当前连接用户
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.getCurrentUserId(function(ret, err) {
api.toast({ msg: ret.result });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
disableLocalNotification
设置本地消息不提示
disableLocalNotification(callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON 对象
- 描述:操作结果
- 内部字段:
{
status: 'success' // 状态码:success / error
}
示例代码
var rong = api.require('rongCloudIM');
// 之前调用 init 和 connect 的代码省略
rong.disableLocalNotification(function(ret, err) {
api.toast({ msg: ret.status });
})
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
会话类型
区分不同的会话形式,字符串类型
取值范围
- PRIVATE (单聊)
- DISCUSSION (讨论组)
- GROUP (群组)
- CHATROOM(聊天室)
- CUSTOMER_SERVICE (客服)
- SYSTEM (系统)
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
会话通知提醒状态
会话通知提醒的状态,开启或者关闭,字符串类型
取值范围
- DO_NOT_DISTURB (免打扰)
- NOTIFY (提醒)
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
讨论组邀请状态
讨论组邀请状态,开放或者关闭,字符串类型
取值范围
- OPENED (开放邀请)
- CLOSED (关闭邀请)
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
连接状态
连接状态,字符串类型
取值范围
- CONNECTED (连接成功)
- CONNECTING (连接中)
- DISCONNECTED (断开连接)
- KICKED (用户账户在其他设备登录,本机会被踢掉线)
- NETWORK_UNAVAILABLE (网络不可用)
- SERVER_INVALID (服务器异常或无法连接)
- TOKEN_INCORRECT (Token 不正确)
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本
## 发送出的消息状态 连接状态,字符串类型 ### 取值范围 - FAILED (发送失败) - SENDING (发送中) - SENT (已发送) ### 可用性 iOS 系统,Android 系统 可提供的 1.0.0 及更高版本接收到的消息状态
接收到的消息状态,字符串类型
取值范围
- UNREAD (未读)
- READ (已读)
- LISTENED (已收听)
- DOWNLOADED ( 已下载)
可用性
iOS 系统,Android 系统
可提供的 1.0.0 及更高版本