rongCloudIM

来自于：融云官方立即使用

• Method
• Constant

注意事项:

使用该模块需要在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 平台上应用的概览里可以查看。

1. 为 App 开启远程推送服务
2. 生成并上传 P12 证书
3. 融云开发者平台上传 p12 证书
4. 生成 provisioning profile 文件
5. 将 provisioning profile 文件上传 APICloud 平台
6. 在 APICloud 平台云编译出 ipa 安装包并安装（正式版发布到苹果商店，通过苹果商店下载安装）
7. 用户允许推送

以上步骤都已经实现后，还需要使用您 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    // 错误码
}

错误说明：

示例代码

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 服务器，进行后续各种方法操作前务必要先调用此方法，（Android自3.2.4版本【包括3.2.4】以后，需要开通音视频服务，否则会导致连接失败）

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    // 错误码
}

错误说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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
}

状态码说明：

示例代码

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 及更高版本

接收到的消息状态

接收到的消息状态，字符串类型

取值范围

• UNREAD （未读）
• READ （已读）
• LISTENED （已收听）
• DOWNLOADED （ 已下载）

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本