Class: Chatroom

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>

收到消息的回调, 会传入消息数组

onTagsUpdate 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:
Returns:
Type
Void
Example
chatroom.connect();

disconnect()

退出聊天室

See:
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);
}

getHistoryMsgsByTags()

根据标签获取聊天室历史消息

  • 获取从 timetag 对应的时间点往前的若干条数据
  • 不填 timetag 的话默认为服务器当前时间
Parameters:
Name Type Argument Default Description
options.tags StringArray

标签数组

options.types NumberArray

消息类型

options.fromTime Number <optional>

开始时间

options.toTime Number <optional>

结束时间

options.limit Number <optional>

数量限制,默认100

options.reverse Number <optional>
0

默认0表示从fromTime开始往前查找历史消息;

options.done function

成功回调

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

kickChatroomMember(options)

踢聊天室成员

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表示移除

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

是否加为普通成员

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表示移除

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表示移除

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表示移除

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)

删除队列元素

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 <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.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)

更新聊天室信息

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 <optional>

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

chatroom.queuelevel Integer <optional>

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

needNotify Boolean

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

custom String <optional>

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

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)

设置聊天室临时禁言

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)

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

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 <optional>

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

antiSpamBusinessId String <optional>

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

needSave String <optional>

可选,默认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)

设置聊天室临时禁言

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);
}