Documentation Class: Chatroom

new Chatroom()

请使用 Chatroom.getInstance 来初始化聊天室.
此接口为单例模式, 对于同一个账号的同一个聊天室, 永远返回同一份实例, 即只有第一次调用会初始化一个实例, 后续调用此接口会直接返回初始化过的实例.

Methods

<static> getInstance(options)

此接口为单例模式, 对于同一个账号, 永远返回同一份实例, 即只有第一次调用会初始化一个实例
后续调用此接口会直接返回初始化过的实例, 同时也会调用接口setOptions更新传入的配置
后续调用此接口时, 如果连接已断开, 会自动建立连接
当发生掉线时，SDK会自动进行重连

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`secure`	Boolean \| Object	<optional>	true	secure 模式下会通过 https 协议跟服务器建立连接, 非 secure 模式下会通过 http 协议跟服务器建立连接, 默认 true
`appKey`	String			在云信管理后台查看应用的 appKey
`account`	String			帐号, 应用内唯一
`token`	String			帐号的 token, 用于建立连接
`chatroomId`	String			聊天室 id
`chatroomAddresses`	Array.<String>			聊天室地址列表
`tags`	Array.<String>	<optional>		标签，可设置多个，仅代表本次登录
`notifyTargetTags`	String	<optional>		登录登出等通知目标的标签，是一个标签表达式
`loginAuthType`	String	<optional>		鉴权方式，0表示最初的loginToken的校验方式，1表示基于appSecret计算的token鉴权方式，2表示基于第三方回调的token鉴权方式，默认0
`loginExt`	String	<optional>		登录自定义字段，用于提交给用户的第三方回调服务进行登录检测
`nosScenes`	String	<optional>	'chatroom'	nos文件存储全局配置，存储场景，实例有效，默认chatroom
`nosSurvivalTime`	Number	<optional>	Infinity	nos文件存储全局配置，存储有效时间，实例有效，默认Infinity 不得小于一天，单位秒
`chatroomNick`	String	<optional>		进入聊天室后展示的昵称, 如果不设置并且托管了用户资料, 那么使用用户资料里面的昵称
`chatroomAvatar`	String	<optional>		进入聊天室后展示的头像, 如果不设置并且托管了用户资料, 那么使用用户资料里面的头像
`chatroomCustom`	String	<optional>		扩展字段, 设置了之后, 通过`getChatroomMembers`获取的聊天室成员信息会包含此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`chatroomEnterCustom`	String	<optional>		扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`onconnect`	function	<optional>		连接建立后的回调, 会传入`聊天室信息`
`onwillreconnect`	function	<optional>		即将重连的回调此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接此回调会收到一个对象, 包含额外的信息, 有以下字段 `duration`: 距离下次重连的时间 `retryCount`: 重连尝试的次数
`reconnectionAttempts`	Number	<optional>		SDK尝试重连的最大次数，超过后则不再尝试重连，并触发`ondisconnect`回调
`loc_x`	Number	<optional>		坐标x,非必传,空间消息专用
`loc_y`	Number	<optional>		坐标y,非必传,空间消息专用
`loc_z`	Number	<optional>		坐标z,非必传,空间消息专用,以上三个参数如果有任一缺少则初始化不会带上坐标信息
`distance`	Number	<optional>		订阅的消息的距离
`ondisconnect`	function	<optional>		断开连接后的回调此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面此回调会收到一个对象, 包含错误的信息, 有以下字段 `code`: 出错时的错误码, 可能为空 `302`: 账号或者密码错误 `'kicked'`: 被踢当`code`为`'kicked'`的时候, 此对象会有以下字段 `reason`: 被踢的原因 `chatroomClosed`: 聊天室关闭了 `managerKick`: 被管理员踢出 `samePlatformKick`: 不允许同一个帐号重复登录同一个聊天室 `message`: 文字描述的被踢的原因
`onerror`	function	<optional>		发生错误的回调, 会传入`错误`对象
`onmsgs`	function	<optional>		收到消息的回调, 会传入`消息`数组

Example

var chatroom = Chatroom.getInstance({
    appKey: 'appKey',
    account: 'account',
    token: 'token',
    chatroomId: 'chatroomId',
    chatroomAddresses: [
        'address1',
        'address2'
    ],
    onconnect: onChatroomConnect,
    onerror: onChatroomError,
    onwillreconnect: onChatroomWillReconnect,
    ondisconnect: onChatroomDisconnect,
    // 消息
    onmsgs: onChatroomMsgs
});
function onChatroomConnect(chatroomInfo) {
    console.log('进入聊天室', chatroomInfo);
}
function onChatroomWillReconnect(obj) {
    // 此时说明 `SDK` 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
    console.log('即将重连', obj);
}
function onChatroomDisconnect(error) {
    // 此时说明 `SDK` 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
    console.log('连接断开', error);
    if (error) {
        switch (error.code) {
        // 账号或者密码错误, 请跳转到登录页面并提示错误
        case 302:
            break;
        // 被踢, 请提示错误后跳转到登录页面
        case 'kicked':
            break;
        default:
            break;
        }
    }
}
function onChatroomError(error, obj) {
    console.log('发生错误', error, obj);
}
function onChatroomMsgs(msgs) {
    console.log('收到聊天室消息', msgs);
}

audioToMp3(options)

将音频 url 转为 mp3

此方法会返回一个新的 url

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`url`	String	url

Returns:

转为 mp3 后的 url

Type: String

Example

var url = 'http://b12026.nos.netease.com/MTAxMTAxMA==/bmltYV8xMTQwMzFfMTQ1MTg4ODk5MjMxMV9mNmI1Y2QyZC03N2UzLTQxNmUtYWY5NC1iODlhZGY4ZTYzYWQ=';
var mp3Url = chatroom.audioToMp3({
    url: url
});
console.log(mp3Url);

connect()

进入聊天室

See:

disconnect

Returns:

Type: Void

Example

chatroom.connect();

disconnect()

退出聊天室

See:

connect

Returns:

Type: Void

Example

chatroom.disconnect();

getChatroom(options)

获取聊天室信息

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`done`	function	结果回调函数, 成功时会额外附上`聊天室信息`

Returns:

Type: Void

Example

chatroom.getChatroom({
    done: getChatroomDone
});
function getChatroomDone(error, obj) {
    console.log('获取聊天室信息' + (!error?'成功':'失败'), error, obj);
}

getChatroomMemberCountByTag(options)

获取带有某标签的在线的聊天室成员数量

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`tag`	string	标签，获取带有这个标签的成员数量
`done`	done	结果回调函数, 成功时会额外附上成员数量

Returns:

Type: Void

Example

chatroom.getChatroomMemberCountByTag({
    tag: 'tag1',
    limit: 100,
    done: (error, obj) => console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members)
});

getChatroomMembers(options)

获取聊天室成员列表

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`guest`	Boolean			`true`表示获取游客, `false`表示获取非游客成员 true 为获取游客列表，默认按加入加入聊天室时间倒序排列 false 为获取非游客（即固定成员）列表，按照成为固定成员的时间倒序排列，默认获取所有（包括不在线的）固定成员
`desc`	Boolean	<optional>	true	对 `guest=true` 时生效 true 为加入聊天室时间降序排列（即加入时间晚的排前面） false 为加入聊天室时间升序排列（即加入时间晚的排后面）
`onlyOnline`	Boolean	<optional>	false	对 `guest=false` 时生效 true 只获取在线的固定成员 false 获取所有（包括不在线的）固定成员
`time`	Number	<optional>	0	分页用, 查找该时间戳之前的成员默认 0 代表当前服务器时间获取游客时, 此字段填上次获取的最后一个游客的`enterTime` 获取非游客时, 此字段填上次获取的最后一个非游客的`updateTime`
`limit`	Number	<optional>	100	分页用, 默认 100
`done`	done			结果回调函数, 成功时会额外附上`聊天室成员信息`列表

Returns:

Type: Void

Example

chatroom.getChatroomMembers({
    guest: false,
    limit: 100,
    done: getChatroomMembersDone
});
function getChatroomMembersDone(error, obj) {
    console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members);
}

getChatroomMembersByTag(options)

获取带有某标签的聊天室成员列表

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`tag`	string			标签，获取带有这个标签的成员
`time`	Number	<optional>	0	起始时间，分页用；逆序查询该时间之后的成员列表第一次不填，默认为0代表当前服务器时间，即获取第一页第二页及之后，填上一页最后一个成员的`enterTime`
`limit`	Number	<optional>	100	分页用, 默认 100
`done`	done			结果回调函数, 成功时会额外附上`聊天室成员信息`列表

Returns:

Type: Void

Example

chatroom.getChatroomMembersByTag({
    tag: 'tag1',
    limit: 100,
    done: (error, obj) => console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members)
});

getChatroomMembersInfo(options)

获取聊天室成员信息

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`accounts`	Array.<String>	待查询的账号列表, 每次最多20个
`done`	function	结果回调函数, 成功时会额外附上`聊天室成员信息`列表

Returns:

Type: Void

Example

chatroom.getChatroomMembersInfo({
    accounts: ['account1', 'account2'],
    done: getChatroomMembersInfoDone
});
function getChatroomMembersInfoDone(erorr, obj) {
    console.log('获取聊天室成员信息' + (!error?'成功':'失败'), error, obj);
}

getHistoryMsgs(options)

获取聊天室历史消息

获取从 timetag 对应的时间点往前的若干条数据
不填 timetag 的话默认为服务器当前时间

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`timetag`	Number	<optional>		时间戳
`limit`	Number	<optional>	100	limit, 默认 100
`reverse`	Boolean	<optional>	false	默认`false`表示从`timetag`开始往前查找历史消息;
`msgTypes`	StringArray	<optional>	['text', 'image', ...]	消息类型列表，默认全部消息类型

Returns:

Type: Void

Example

chatroom.getHistoryMsgs({
    timetag: 1451393192478,
    limit: 100,
    done: getHistoryMsgsDone
});
function getHistoryMsgsDone(error, obj) {
    console.log('获取聊天室历史' + (!error?'成功':'失败'), error, obj.msgs);
}

kickChatroomMember(options)

踢聊天室成员

当有人被踢出聊天室时, 所有聊天室成员会收到类型为'kickMember'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`account`	String		待踢的账号
`custom`	String	<optional>	扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段, 被踢的人收到的`ondisconnect`回调接收的参数的`custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function		结果回调函数

Returns:

Type: Void

Example

chatroom.kickChatroomMember({
    account: 'account',
    done: kickChatroomMemberDone
});
function kickChatroomMember(error, obj) {
    console.log('踢人' + (!error?'成功':'失败'), error, obj);
}

markChatroomBlacklist(options)

设置聊天室黑名单

被加入黑名单的人将不能进入此聊天室

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`account`	String		待设置的账号
`isAdd`	Boolean		`true`表示添加, `false`表示移除当有人被`加入黑名单`时, 所有聊天室成员会收到类型为`'blackMember'`的`聊天室通知消息`。当有人被`移除黑名单`时, 所有聊天室成员会收到类型为`'blackMember'`的`聊天室通知消息`。
`custom`	String	<optional>	扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function		结果回调函数, 成功时会额外附上`聊天室成员信息`

Returns:

Type: Void

Example

chatroom.markChatroomBlacklist({
    account: 'account',
    isAdd: true,
    done: markChatroomBlacklistDone
});
function markChatroomBlacklistDone(error, obj) {
    console.log('添加聊天室黑名单' + (!error?'成功':'失败'), error, obj.member);
}

markChatroomCommonMember(options)

设置聊天室普通成员

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`account`	String			待设置的账号
`isAdd`	Boolean			是否加为普通成员当有人被`加为普通成员`时, 所有聊天室成员会收到类型为`'addCommon'`的`聊天室通知消息`。当有人被`移除普通成员`时, 所有聊天室成员会收到类型为`'removeCommon'`的`聊天室通知消息`。
`level`	Number	<optional>	0	等级
`custom`	String	<optional>		扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function			结果回调函数

Returns:

Type: Void

Example

chatroom.markChatroomCommonMember({
    account: 'account',
    level: 0,
    done: markChatroomCommonMemberDone
});
function markChatroomCommonMemberDone(error) {
    console.log('设置聊天室普通成员' + (!error?'成功':'失败'), error);
}

markChatroomGaglist(options)

设置聊天室禁言名单

被加入禁言名单的人将不能在该聊天室发送消息

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`account`	String		待设置的账号
`isAdd`	Boolean		`true`表示添加, `false`表示移除当有人被`加入禁言名单`时, 所有聊天室成员会收到类型为`'gagMember'`的`聊天室通知消息`。当有人被`移除禁言名单`时, 所有聊天室成员会收到类型为`'ungagMember'`的`聊天室通知消息`。
`custom`	String	<optional>	扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function		结果回调函数, 成功时会额外附上`聊天室成员信息`

Returns:

Type: Void

Example

chatroom.markChatroomGaglist({
    account: 'account',
    isAdd: true,
    done: markChatroomGaglistDone
});
function markChatroomGaglistDone(error, obj) {
    console.log('添加聊天室禁言名单' + (!error?'成功':'失败'), error, obj.member);
}

markChatroomIdentity(options)

设置聊天室成员身份

管理员可以设置聊天室普通成员, 设置聊天室黑名单, 设置聊天室禁言名单, 踢聊天室成员

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`account`	String		待设置的账号
`identity`	String		待设置的身份，如果不是以下身份则默认设置为普通成员 `'manager'` (管理员) `'common'` (普通成员) `'black'` (拉黑) `'mute'` (禁言)
`isAdd`	Boolean		`true`表示添加, `false`表示移除当有人被`加为管理员`时, 所有聊天室成员会收到类型为`'addManager'`的`聊天室通知消息`。当有人被`移除管理员`时, 所有聊天室成员会收到类型为`'removeManager'`的`聊天室通知消息`。
`custom`	String	<optional>	扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function		结果回调函数, 成功时会额外附上`聊天室成员信息`

Returns:

Type: Void

Example

chatroom.markChatroomIdentity({
    account: 'account',
    identity: 'common',
    isAdd: true,
    done: markChatroomIdentityDone
});
function markChatroomIdentityDone(error, obj) {
    console.log('设置聊天室成员身份' + (!error?'成功':'失败'), error, obj.member);
}

markChatroomManager(options)

设置聊天室管理员

管理员可以设置聊天室普通成员, 设置聊天室黑名单, 设置聊天室禁言名单, 踢聊天室成员

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`account`	String		待设置的账号
`isAdd`	Boolean		`true`表示添加, `false`表示移除当有人被`加为管理员`时, 所有聊天室成员会收到类型为`'addManager'`的`聊天室通知消息`。当有人被`移除管理员`时, 所有聊天室成员会收到类型为`'removeManager'`的`聊天室通知消息`。
`custom`	String	<optional>	扩展字段, 如果填了, 那么其它聊天室成员收到的`聊天室通知消息`的`attach.custom`的值为此字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`done`	function		结果回调函数, 成功时会额外附上`聊天室成员信息`

Returns:

Type: Void

Example

chatroom.markChatroomManager({
    account: 'account',
    isAdd: true,
    done: markChatroomManagerDone
});
function markChatroomManagerDone(error, obj) {
    console.log('添加聊天室管理员' + (!error?'成功':'失败'), error, obj.member);
}

packFileDownloadName(options)

修改图片下载的名字

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`url`	String	原图 url
`name`	String	下载的名字

Returns:

修改图片下载名字后的图片 url

Type: String

Example

var url = 'http://nim.nos.netease.com/MTAxMTAwMg==/bmltYV8xNDc5OTNfMTQ0MzE0NTgyNDI0M184YjFkYTMwMS02NjcxLTRiYjktYTUwZC04ZTVlZjZlNzZjMzA=';
var nameUrl = chatroom.packFileDownloadName({
    url: url,
    name: '测试.jpg'
});
console.log(nameUrl);

peak(options)

获取聊天室队列中第一个元素

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.peak({
  done: peakDone
})
function peakDone (error, obj, content) {
  console.log('获取聊天室队列中第一个元素' + (!error?'成功':'失败'), error, obj, content);
}

previewFile(options)

预览文件

开发者可以预览文件, 支持以下几种场景
- 通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
- 通过参数blob传入 Blob 对象
- 通过参数filePath 供小程序，RN，Node使用, 举例小程序可通过 wx.chooseImage 或者 wx.startRecord 拿到的临时文件路径
- 通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL, 此用法需要浏览器支持 Blob
SDK会将文件上传到文件服务器, 然后将拿到的文件对象在done回调中传给开发者, 文件对象有以下几种
- 图片对象
- 音频对象
- 视频对象
- 文件对象
开发者在拿到文件对象之后, 可以调用发送文件消息来发送文件消息。
文件大小限制为最大 100M
- 高级浏览器会在上传前就检测文件大小
- IE8/IE9 会在上传完成后检测文件大小

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`type`	String	<optional>	文件过滤器 image会过滤掉非图片的文件, audio过滤掉非音频, video会过滤掉非视频的文件 IE8/IE9 不支持文件过滤
`fileInput`	String \| Node	<optional>	文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
`filePath`	String	<optional>	仅供小程序(5.1.0+)、nodejs(5.4.0+)、react-native(5.3.0+)使用, 举例小程序通过 wx.chooseImage 或者 wx.startRecord 拿到临时文件路径 filePath 再传入。
`blob`	Blob	<optional>	Blob 对象
`dataURL`	String	<optional>	包含 MIME type 和 base64 数据的 data URL
`uploadprogress`	uploadprogress	<optional>	上传进度, ie9以下不支持上传进度
`nosScenes`	String	<optional>	存储场景，不传默认全局实例配置
`nosSurvivalTime`	Number	<optional>	存储有效时间，传默认全局实例配置不得小于一天，单位秒
`transcode`	Boolean	<optional>	仅当 type 为 file 时，此参数为 true，举例 docx 文件上传后还会被转换为图片。
`done`	done		结果回调函数, 成功时会收到文件对象, 请参考 `图片对象` `音频对象` `视频对象` `文件对象`

Returns:

Type: Void

Example

chatroom.previewFile({
    type: 'image',
    fileInput: fileInput,
    uploadprogress: function(obj) {
        console.log('文件总大小: ' + obj.total + 'bytes');
        console.log('已经上传的大小: ' + obj.loaded + 'bytes');
        console.log('上传进度: ' + obj.percentage);
        console.log('上传进度文本: ' + obj.percentageText);
    },
    done: function(error, file) {
        console.log('上传image' + (!error?'成功':'失败'));
        // show file to the user
        if (!error) {
            var msg = chatroom.sendFile({
                scene: 'p2p',
                to: 'account',
                file: file,
                done: sendChatroomMsgDone
            });
            console.log('正在发送聊天室image消息, id=' + msg.idClient);
        }
    }
});

queueChange(options)

批量更新聊天室队列

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`elementMap`	String	批量更新元素的key-value对，key/value分别是elementKey和elementValue（elementKey限制128字节,elementValue限制4096字节），一次最多更新100个
`needNotify`	Boolean	是否需要发送广播通知，可选参数，不传默认false，当设置为 true 时，所有聊天室成员会收到类型为`'updateQueue'`的`聊天室通知消息`。
`notifyExt`	String	通知中的自定义字段，长度限制2048
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.queueChange({
  elementMap: {
    elementKey1: newElementValue
  },
  transient: true,
  notifyExt: 'queueChange',
  done: queueChangeDone
})
function queueChangeDone (error, obj, content) {
  console.log('批量更新聊天室队列' + (!error?'成功':'失败'), error, obj, content);
}

queueDrop(options)

清除聊天室队列

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.queueDrop({
  done: dropDone
})
function dropDone (error, obj, content) {
  console.log('清除聊天室队列' + (!error?'成功':'失败'), error, obj, content);
}

queueList(options)

获取聊天室队列列表

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.queueList({
  done: queueListDone
})
function queueListDone (error, obj, content) {
  console.log('获取聊天室队列列表' + (!error?'成功':'失败'), error, obj, content);
}

queueOffer(options)

新加(更新)队列元素

当新加(更新)队列元素时, 所有聊天室成员会收到类型为'updateQueue'的聊天室通知消息。如果elementKey对应的元素已经在队列中存在了，那就是更新操作，如果不存在，就放到队列尾部.

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`elementKey`	String	新元素的UniqKey，长度限制128字节
`elementValue`	String	新元素内容，长度限制4096字节
`transient`	Boolean	可选参数，不传默认false，当提交这个新元素的用户从聊天室掉线或退出的时候，是否需要删除这个元素。
`elementAccount`	String	可选参数，队列元素所属账号，默认不传表示队列元素属于当前操作人，管理员可以指定队列元素归属于其他合法账号
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.queueOffer({
  elementKey: ‘elementKey1’,
  elementValue: ‘elementValue1’,
  transient: true,
  done: queueOfferDone
})
function queueOfferDone (error, obj, content) {
  console.log('新加(更新)队列元素' + (!error?'成功':'失败'), error, obj, content);
}

queuePoll(options)

删除队列元素

当删除队列元素时, 所有聊天室成员会收到类型为'updateQueue'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`elementKey`	String	需要取出的元素的UniqKey, 传空传表示取出第一个元素
`done`	function	结果回调函数

Returns:

Type: Void

Example

chatroom.queuePoll({
  elementKey: ‘elementKey1’,
  done: queuePollDone
})
function queuePollDone (error, obj, content) {
  console.log('删除队列元素' + (!error?'成功':'失败'), error, obj, content);
}

sendCustomMsg(options)

发送自定义消息

自定义消息是消息类型的一种

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`content`	String		自定义消息的消息内容, 推荐使用JSON格式构建
`notifyTargetTags`	String	<optional>	本条消息的目标标签，符合该标签条件的成员才会收到消息通知；若缺失，则使用发送者登录时设置的`notifyTargetTags`，若仍缺失，则消息会发送给聊天室内的所有人
`resend`	Boolean	<optional>	是否是重发
`idClient`	String	<optional>	如果是重发, 那么需要带上之前生成的idClient来标记这条消息
`custom`	String	<optional>	扩展字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`fromNick`	String	<optional>	发送方的昵称
`yidunAntiCheating`	String	<optional>	易盾反作弊字段，长度限制1024，JSON字符串格式。如：`"{"email":"test@163.com","phone":"12345678901","token":"1234","extension":"hello"}"`
`yidunAntiSpamExt`	String	<optional>	易盾反作弊扩展字段字段，2021-08-09 追加。限制 JSON 格式字符串，长度上限 1024
`subType`	Interger	<optional>	消息子类型，格式为大于0的整数，开发者可自定义
`env`	String	<optional>	环境变量，用于指向不同的抄送、第三方回调等配置
`done`	done		结果回调函数

Returns:

消息

Type: Message

Example

var value = Math.ceil(Math.random()*3);
var content = {
    type: 1,
    data: {
        value: value
    }
};
var msg = chatroom.sendCustomMsg({
    content: JSON.stringify(content),
    done: sendChatroomMsgDone
});
console.log('正在发送聊天室自定义消息, id=' + msg.idClient);

sendFile(options)

发送文件消息

文件消息是消息类型的一种
开发者可以直接发送文件消息
- 支持以下几种场景
  - 通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
  - 通过参数blob传入 Blob 对象
  - 通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL, 此用法需要浏览器支持 Blob
- SDK会先将文件上传到文件服务器, 然后把拿到的文件对象在uploaddone回调中传给用户, 然后将其拼装成文件消息发送出去。
开发者也可以先预览文件来获取文件对象, 然后调用此接口发送文件消息。
- 通过参数file传入文件
直接发送文件消息的话会在beforesend回调里面传入SDK生成的idClient, 如果先预览文件再发送, 那么此接口会直接返回idClient
参数type指定了要发送的文件类型, 包括图片、音频、视频和普通文件, 对应的值分别为'image'、'audio'、'video'和'file', 不传默认为'file'。
图片、音频、视频和普通文件的区别在于具体的文件信息不一样, 具体字段请参考
- 图片对象
- 音频对象
- 视频对象
- 文件对象
文件大小限制为最大100M
- 高级浏览器会在上传前就检测文件大小
- IE8和IE9会在上传完成后检测文件大小

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`type`	String	<optional>		文件过滤器, `'image'`会过滤掉非图片的文件, `'audio'`过滤掉非音频, `'video'`会过滤掉非视频的文件, IE8/IE9 不支持文件过滤
`fileInput`	String \| Node	<optional>		文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
`blob`	Blob	<optional>		Blob 对象
`dataURL`	String	<optional>		MIME type 和 base64 数据的 data URL
`file`	Array	<optional>		文件对象, 开发者可以通过`预览文件`拿到文件对象
`filePath`	String	<optional>		仅供小程序(5.1.0+)、nodejs(5.4.0+)、react-native(5.3.0+)使用, 举例小程序通过 wx.chooseImage 或者 wx.startRecord 拿到临时文件路径 filePath 再传入。
`resend`	Boolean	<optional>	false	是否是重发
`beginupload`	function	<optional>		开始上传图片的回调如果开发者传入 fileInput, 在此回调之前不能修改 fileInput 在此回调之后可以取消图片上传, 此回调会接收一个参数 `upload`, 调用 `upload.abort();` 来取消文件上传
`uploadprogress`	uploadprogress	<optional>		上传进度, IE9以下不支持上传进度
`uploaddone`	uploaddone	<optional>		上传完成回调
`beforesend`	beforesend	<optional>		发送文件消息之前的回调函数
`resend`	Boolean	<optional>		是否是重发
`idClient`	String	<optional>		如果是重发, 那么需要带上之前生成的idClient来标记这条消息
`custom`	String	<optional>		扩展字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`fromNick`	String	<optional>		发送方的昵称
`nosScenes`	String	<optional>		存储场景，不传默认全局实例配置
`nosSurvivalTime`	Number	<optional>		存储有效时间，传默认全局实例配置不得小于一天，单位秒
`yidunAntiCheating`	String	<optional>		易盾反作弊字段，长度限制1024，JSON字符串格式。如：`"{"email":"test@163.com","phone":"12345678901","token":"1234","extension":"hello"}"`
`yidunAntiSpamExt`	String	<optional>		易盾反作弊扩展字段字段，2021-08-09 追加。限制 JSON 格式字符串，长度上限 1024
`subType`	Interger	<optional>		消息子类型，格式为大于0的整数，开发者可自定义
`env`	String	<optional>		环境变量，用于指向不同的抄送、第三方回调等配置
`notifyTargetTags`	String	<optional>		本条消息的目标标签，符合该标签条件的成员才会收到消息通知；若缺失，则使用发送者登录时设置的`notifyTargetTags`，若仍缺失，则消息会发送给聊天室内的所有人
`toAccids`	Array	<optional>		字符串数组，内容是消息接受者账号，如果设置了本字段，且不为空，则本消息为聊天室定向消息（聊天室定向消息不会存历史）
`done`	done			结果回调函数

Returns:

如果提供了参数fileInput, 那么先上传文件到服务器再发送, 不会返回消息, 会在beforesend里面返回消息.
如果提供了参数file, 那么直接发送文件消息, 返回消息

Type: Void | Message

Example

chatroom.sendFile({
    type: 'image',
    fileInput: fileInput,
    uploadprogress: function(obj) {
        console.log('文件总大小: ' + obj.total + 'bytes');
        console.log('已经上传的大小: ' + obj.loaded + 'bytes');
        console.log('上传进度: ' + obj.percentage);
        console.log('上传进度文本: ' + obj.percentageText);
    },
    uploaddone: function(error, file) {
        console.log('上传' + (!error?'成功':'失败'), error, file);
    },
    beforesend: function(msg) {
        console.log('正在发送聊天室image消息, id=' + msg.idClient);
    },
    done: sendChatroomMsgDone
});

sendGeo(options)

发送地理位置消息

地理位置消息是消息类型的一种, geo参数请参考地理位置对象

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name Type Argument Description

geo

Object

地理位置对象

Properties

Name	Type	Description
`lng`	Number	经度
`lat`	Number	纬度
`title`	String	地址描述

notifyTargetTags

String

本条消息的目标标签，符合该标签条件的成员才会收到消息通知；若缺失，则使用发送者登录时设置的notifyTargetTags，若仍缺失，则消息会发送给聊天室内的所有人

resend

Boolean

是否是重发

idClient

String

如果是重发, 那么需要带上之前生成的idClient来标记这条消息

custom

String

扩展字段

推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃

yidunAntiCheating

String

易盾反作弊字段，长度限制1024，JSON字符串格式。如："{"email":"test@163.com","phone":"12345678901","token":"1234","extension":"hello"}"

yidunAntiSpamExt

String

易盾反作弊扩展字段字段，2021-08-09 追加。限制 JSON 格式字符串，长度上限 1024

subType

Interger

消息子类型，格式为大于0的整数，开发者可自定义

toAccids

Array

字符串数组，内容是消息接受者账号，如果设置了本字段，且不为空，则本消息为聊天室定向消息（聊天室定向消息不会存历史）

env

String

环境变量，用于指向不同的抄送、第三方回调等配置

Returns:

消息

Type: Message

Example

var msg = chatroom.sendGeo({
    scene: 'p2p',
    to: 'account',
    geo: {
        lng: '116.3833',
        lat: '39.9167',
        title: 'Beijing'
    },
    done: sendChatroomMsgDone
});
console.log('正在发送聊天室geo消息, id=' + msg.idClient);

sendText(options)

发送文本消息

文本消息是消息的一种, 请参考消息

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Default	Description
`text`	String			文本消息内容
`notifyTargetTags`	String	<optional>		本条消息的目标标签，符合该标签条件的成员才会收到消息通知；若缺失，则使用发送者登录时设置的`notifyTargetTags`，若仍缺失，则消息会发送给聊天室内的所有人
`resend`	Boolean	<optional>		是否是重发
`idClient`	String	<optional>		如果是重发, 那么需要带上之前生成的idClient来标记这条消息
`custom`	String	<optional>		扩展字段
`clientAntiSpam`	Boolean	<optional>	false	是否需要过客户端反垃圾推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`yidunAntiCheating`	String	<optional>		易盾反作弊字段，长度限制1024，JSON字符串格式。如：`"{"email":"test@163.com","phone":"12345678901","token":"1234","extension":"hello"}"`
`yidunAntiSpamExt`	String	<optional>		易盾反作弊扩展字段字段，2021-08-09 追加。限制 JSON 格式字符串，长度上限 1024
`subType`	Interger	<optional>		消息子类型，格式为大于0的整数，开发者可自定义
`env`	String	<optional>		环境变量，用于指向不同的抄送、第三方回调等配置
`toAccids`	Array	<optional>		字符串数组，内容是消息接受者账号，如果设置了本字段，且不为空，则本消息为聊天室定向消息（聊天室定向消息不会存历史）
`loc_x`	Number	<optional>		坐标x
`loc_y`	Number	<optional>		坐标y
`loc_z`	Number	<optional>		坐标z，以上三个参数如果有任一缺少则不会带上坐标信息
`done`	done			结果回调函数

Returns:

消息

Type: Message

Example

var msg = chatroom.sendText({
    text: 'hello',
    done: sendChatroomMsgDone
});
console.log('正在发送聊天室text消息, id=' + msg.idClient);
function sendChatroomMsgDone(error, msg) {
    console.log('发送聊天室' + msg.type + '消息' + (!error?'成功':'失败') + ', id=' + msg.idClient, error, msg);
}

sendTipMsg(options)

发送提醒消息

提醒消息是消息类型的一种
提醒消息用于会话内的状态提醒，如进入会话时出现的欢迎消息，或者会话命中敏感词后的提示消息等等.

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`tip`	String		提醒内容
`notifyTargetTags`	String	<optional>	本条消息的目标标签，符合该标签条件的成员才会收到消息通知；若缺失，则使用发送者登录时设置的`notifyTargetTags`，若仍缺失，则消息会发送给聊天室内的所有人
`resend`	Boolean	<optional>	是否是重发
`idClient`	String	<optional>	如果是重发, 那么需要带上之前生成的idClient来标记这条消息
`custom`	String	<optional>	扩展字段推荐使用`JSON`格式构建, 非`JSON`格式的话, Web端会正常接收, 但是会被其它端丢弃
`yidunAntiCheating`	String	<optional>	易盾反作弊字段，长度限制1024，JSON字符串格式。如：`"{"email":"test@163.com","phone":"12345678901","token":"1234","extension":"hello"}"`
`yidunAntiSpamExt`	String	<optional>	易盾反作弊扩展字段字段，2021-08-09 追加。限制 JSON 格式字符串，长度上限 1024
`subType`	Interger	<optional>	消息子类型，格式为大于0的整数，开发者可自定义
`toAccids`	Array	<optional>	字符串数组，内容是消息接受者账号，如果设置了本字段，且不为空，则本消息为聊天室定向消息（聊天室定向消息不会存历史）
`env`	String	<optional>	环境变量，用于指向不同的抄送、第三方回调等配置

Returns:

消息

Type: Message

Example

var msg = chatroom.sendTipMsg({
    scene: 'p2p',
    to: 'account',
    tip: 'tip content',
    done: sendChatroomMsgDone
});
console.log('正在发送聊天室提醒消息, id=' + msg.idClient);

setOptions(options)

更新聊天室配置, 参数格式跟 Chatroom.getInstance 保持一致

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`token`	String	帐号的 token, 用于建立连接

Example

// 更新 token 的例子
chatroom.setOptions({
    token: 'newToken'
});

updateChatroom(options)

更新聊天室信息

当更新聊天室时, 所有聊天室成员会收到类型为'updateChatroom'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name Type Argument Description

chatroom

Object

待更新的聊天室信息

Properties

Name	Type	Argument	Description
`name`	String	<optional>	聊天室名字
`announcement`	String	<optional>	聊天室公告
`broadcastUrl`	String	<optional>	直播地址
`custom`	String	<optional>	扩展字段

antiSpamBusinessId

String

用户配置的对某些资料内容另外的反垃圾的业务ID

chatroom.queuelevel

Integer

队列管理权限：0:所有人都有权限变更队列，1:只有主播管理员才能操作变更

needNotify

Boolean

是否需要下发对应的通知消息

custom

String

对应的通知消息的扩展字段

done

function

结果回调函数

Returns:

Type: Void

Example

chatroom.updateChatroom({
  chatroom: {
    name: 'newName',
    announcement: 'newAnnouncement',
    broadcastUrl: 'newBroadcastUrl',
    custom: 'newCustom',
    queuelevel: 'newQueuelevel',
  },
  needNotify: true,
  custom: 'biu',
  done: updateChatroomDone
})
function updateChatroomDone () {
  console.log('更新聊天室信息' + (!error?'成功':'失败'), error, obj);
}

updateChatroomMemberTempMute(options)

设置聊天室临时禁言

当有人被设置聊天室临时禁言时，所有聊天室成员会收到类型为'addTempMute' or 'removeTempMute'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`account`	String	帐号
`duration`	Number	禁言时长，单位秒，传0表示解除禁言
`needNotify`	Boolean	是否需要下发对应的通知消息
`custom`	String	对应的通知消息的扩展字段

Returns:

Type: Void

Example

chatroom.updateChatroomMemberTempMute({
  account: 'account',
  duration: 60,
  needNotify: true,
  custom: 'biu',
  done: updateChatroomMemberTempMuteDone
})
function updateChatroomMemberTempMuteDone(error, obj) {
  console.log('设置聊天室临时禁言' + (!error?'成功':'失败'), error, obj);
}

updateCoordinate(options)

更新坐标

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Description
`x`	Double	坐标x,非必传,空间消息专用
`y`	Double	坐标y,非必传,空间消息专用
`z`	Double	坐标z,非必传,空间消息专用,以上三个参数如果有任一缺少则初始化不会带上坐标信息
`distance`	Double	订阅的消息的距离

Returns:

Type: Void

Example

chatroom.updateCoordinate({
  x: 1.2,
  y: 1.3,
  z: 1.4,
  distance: 5.6,
  done: updateCoordinateDone
})
function updateCoordinateDone(error, obj) {
  console.log('更新坐标' + (!error?'成功':'失败'), error, obj);
}

updateMyChatroomMemberInfo(options)

更新自己在聊天室内的信息

当更新自己在聊天室内的信息时, 所有聊天室成员会收到类型为'updateMemberInfo'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name Type Argument Description

member

Object

待更新的成员信息

Properties

Name	Type	Argument	Description
`nick`	String	<optional>	聊天室内的昵称
`avatar`	String	<optional>	聊天室内的头像
`custom`	String	<optional>	第三方扩展字段

needNotify

Boolean

是否需要下发对应的通知消息

custom

String

对应的通知消息的扩展字段

antiSpamBusinessId

String

用户配置的对某些资料内容另外的反垃圾的业务ID

needSave

String

可选，默认false，是否支持nick,avator和custom字段的持久化（固定成员有效）

done

function

结果回调函数

Returns:

Type: Void

Example

chatroom.updateMyChatroomMemberInfo({
  member: {
    nick: 'newNick',
    avatar: 'newAvatar',
    custom: 'newCustom',
  },
  needNotify: true,
  needSave: true,
  custom: 'biu',
  done: updateMyChatroomMemberInfoDone
})
function updateMyChatroomMemberInfoDone (error, obj) {
  console.log('更新自己在聊天室内的信息' + (!error?'成功':'失败'), error, obj);
}

updateTagMembersTempMute(options)

设置聊天室临时禁言

当有人被设置聊天室临时禁言时，所有聊天室成员会收到类型为'addTempMuteTag' or 'removeTempMuteTag'的聊天室通知消息。

Parameters:

Name Type Description

options

Object

配置参数

Properties

Name	Type	Argument	Description
`tag`	String		禁言的tag
`duration`	Number		禁言时长，单位秒，传0表示解除禁言
`needNotify`	Boolean		是否需要下发对应的通知消息
`notifyTargetTags`	String	<optional>	通知消息广播的目标标签，默认是`options.tag`
`custom`	String	<optional>	对应的通知消息的扩展字段

Returns:

Type: Void

Example

chatroom.updateTagMembersTempMute({
  tag: 'tag1',
  duration: 60,
  needNotify: true,
  custom: 'biu',
  done: updateTagMembersTempMuteDone
})
function updateTagMembersTempMuteDone(error, obj) {
  console.log('设置聊天室临时禁言' + (!error?'成功':'失败'), error, obj);
}