云信api_云信Web SDK API文档

staticChatroom.getInstance(options)

此接口为单例模式, 对于同一个账号, 永远返回同一份实例, 即只有第一次调用会初始化一个实例

后续调用此接口会直接返回初始化过的实例, 同时也会调用接口setOptions更新传入的配置

后续调用此接口时, 如果连接已断开, 会自动建立连接

当发生掉线时，SDK会自动进行重连

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

appKey

String

在云信管理后台查看应用的 appKey

account

String

帐号, 应用内唯一

token

String

帐号的 token, 用于建立连接

chatroomId

String

聊天室 id

chatroomAddresses

Array.

聊天室地址列表

onconnect

function

optional

连接建立后的回调, 会传入聊天室信息

onwillreconnect

function

optional

即将重连的回调

此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接

此回调会收到一个对象, 包含额外的信息, 有以下字段duration: 距离下次重连的时间

retryCount: 重连尝试的次数

ondisconnect

function

optional

断开连接后的回调

此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面

此回调会收到一个对象, 包含错误的信息, 有以下字段code: 出错时的错误码, 可能为空302: 账号或者密码错误

'kicked': 被踢

当code为'kicked'的时候, 此对象会有以下字段reason: 被踢的原因chatroomClosed: 聊天室关闭了

managerKick: 被管理员踢出

samePlatformKick: 不允许同一个帐号重复登录同一个聊天室

message: 文字描述的被踢的原因

onerror

function

optional

发生错误的回调, 会传入错误对象

onmsgs

function

optional

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

Example:

var chatroom = new Chatroom({

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){String}

将音频 url 转为 mp3

此方法会返回一个新的 url

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

url

String

url

Returns:

Type

Description

String

转为 mp3 后的 url

Example:

var url = 'http://b12026.nos.netease.com/MTAxMTAxMA==/bmltYV8xMTQwMzFfMTQ1MTg4ODk5MjMxMV9mNmI1Y2QyZC03N2UzLTQxNmUtYWY5NC1iODlhZGY4ZTYzYWQ=';

var mp3Url = chatroom.audioToMp3({

url: url

});

console.log(mp3Url);

connect(){Void}

进入聊天室

Returns:

Type

Description

Void

Example:

chatroom.connect();See:

disconnect(){Void}

退出聊天室

Returns:

Type

Description

Void

Example:

chatroom.disconnect();See:

getChatroom(options){Void}

获取当前聊天室的信息

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

done

function

结果回调函数, 成功时会额外附上聊天室信息

Returns:

Type

Description

Void

Example:

chatroom.getChatroom({

done: getChatroomDone

});

function getChatroomDone(error, obj) {

console.log('获取当前聊天室的信息' + (!error?'成功':'失败'), error, obj);

}

getChatroomMembers(options){Void}

获取聊天室成员列表

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Default

Description

guest

Boolean

true表示获取游客, false表示获取非游客成员

游客列表按照游客进入聊天室的时间倒序排列

非游客(即固定成员)列表按照成为固定成员的时间倒序排列

onlyOnline

Boolean

false

optional

当设置guest=false来获取非游客成员时, 默认会获取所有的固定成员, 包括不在线的, 可以设置onlyOnline=true来只获取在线的固定成员

time

Number

0

optional

分页用, 查找该时间戳之前的成员

默认 0 代表当前服务器时间

获取游客时, 此字段填上次获取的最后一个游客的enterTime

获取非游客时, 此字段填上次获取的最后一个非游客的updateTime

limit

Number

100

optional

分页用, 默认 100

done

结果回调函数, 成功时会额外附上聊天室成员信息列表

Returns:

Type

Description

Void

Example:

chatroom.getChatroomMembers({

guest: false,

limit: 100,

done: getChatroomMembersDone

});

function getChatroomMembersDone(error, obj) {

console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members);

}

getChatroomMembersInfo(options){Void}

获取聊天室成员信息

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

accounts

Array.

待查询的账号列表

done

function

结果回调函数, 成功时会额外附上聊天室成员信息列表

Returns:

Type

Description

Void

Example:

chatroom.getChatroomMembersInfo({

accounts: ['account1', 'account2'],

done: getChatroomMembersInfoDone

});

function getChatroomMembersInfo(erorr, obj) {

console.log('获取聊天室成员信息' + (!error?'成功':'失败'), error, obj);

}

getHistoryMsgs(options){Void}

获取聊天室历史消息

获取从 timetag 对应的时间点往前的若干条数据

不填 timetag 的话默认为服务器当前时间

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Default

Description

timetag

Number

optional

时间戳

limit

Number

100

optional

limit, 默认 100

Returns:

Type

Description

Void

Example:

chatroom.getHistoryMsgs({

timetag: 1451393192478,

limit: 100,

done: getHistoryMsgsDone

});

function getHistoryMsgsDone(error, obj) {

console.log('获取聊天室历史' + (!error?'成功':'失败'), error, obj.msgs);

}

kickChatroomMember(options){Void}

踢聊天室成员

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

account

String

待踢的账号

custom

String

optional

扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段, 被踢的人收到的ondisconnect回调接收的参数的custom的值为此字段

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

done

function

结果回调函数

Returns:

Type

Description

Void

Example:

chatroom.kickChatroomMember({

account: 'account',

done: kickChatroomMemberDone

});

function kickChatroomMember(error, obj) {

console.log('踢人' + (!error?'成功':'失败'), error, obj);

}

markChatroomBlacklist(options){Void}

设置聊天室黑名单

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

account

String

待设置的账号

isAdd

Boolean

true表示添加, false表示移除

custom

String

optional

扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段

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

done

function

结果回调函数, 成功时会额外附上聊天室成员信息

Returns:

Type

Description

Void

Example:

chatroom.markChatroomBlacklist({

account: 'account',

isAdd: true,

done: markChatroomBlacklistDone

});

function markChatroomBlacklistDone(error, obj) {

console.log('添加聊天室黑名单' + (!error?'成功':'失败'), error, obj.member);

}

markChatroomCommonMember(options){Void}

设置聊天室普通成员

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Default

Description

account

String

待设置的账号

isAdd

Boolean

是否加为普通成员

level

Number

0

optional

等级

custom

String

optional

扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段

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

done

function

结果回调函数

Returns:

Type

Description

Void

Example:

chatroom.markChatroomCommonMember({

account: 'account',

level: 0,

done: markChatroomCommonMemberDone

});

function markChatroomCommonMemberDone(error) {

console.log('设置聊天室普通成员' + (!error?'成功':'失败'), error);

}

markChatroomGaglist(options){Void}

设置聊天室禁言名单

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

account

String

待设置的账号

isAdd

Boolean

true表示添加, false表示移除

custom

String

optional

扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段

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

done

function

结果回调函数, 成功时会额外附上聊天室成员信息

Returns:

Type

Description

Void

Example:

chatroom.markChatroomGaglist({

account: 'account',

isAdd: true,

done: markChatroomGaglistDone

});

function markChatroomGaglistDone(error, obj) {

console.log('添加聊天室禁言名单' + (!error?'成功':'失败'), error, obj.member);

}

markChatroomManager(options){Void}

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

account

String

待设置的账号

isAdd

Boolean

true表示添加, false表示移除

custom

String

optional

扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段

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

done

function

结果回调函数, 成功时会额外附上聊天室成员信息

Returns:

Type

Description

Void

Example:

chatroom.markChatroomManager({

account: 'account',

isAdd: true,

done: markChatroomManagerDone

});

function markChatroomManagerDone(error, obj) {

console.log('添加聊天室管理员' + (!error?'成功':'失败'), error, obj.member);

}

packFileDownloadName(options){String}

修改图片下载的名字

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

url

String

原图 url

name

String

下载的名字

Returns:

Type

Description

String

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

Example:

var url = 'http://nim.nos.netease.com/MTAxMTAwMg==/bmltYV8xNDc5OTNfMTQ0MzE0NTgyNDI0M184YjFkYTMwMS02NjcxLTRiYjktYTUwZC04ZTVlZjZlNzZjMzA=';

var nameUrl = chatroom.packFileDownloadName({

url: url,

name: '测试.jpg'

});

console.log(nameUrl);

previewFile(options){Void}

预览文件

开发者可以预览文件, 支持以下几种场景通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件

通过参数blob传入 Blob 对象

通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL

SDK会将文件上传到文件服务器, 然后将拿到的文件对象在done回调中传给开发者, 文件对象有以下几种

开发者在拿到文件对象之后, 可以调用发送文件消息来发送文件消息。

文件大小限制为最大 100M高级浏览器会在上传前就检测文件大小

IE8/IE9 会在上传完成后检测文件大小

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

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

uploadprogress

optional

上传进度, ie9以下不支持上传进度

done

结果回调函数, 成功时会收到文件对象, 请参考

Returns:

Type

Description

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

}

}

});See:

sendCustomMsg(options)

发送自定义消息

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

content

String

自定义消息的消息内容, 推荐使用JSON格式构建

resend

Boolean

optional

是否是重发

idClient

String

optional

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

custom

String

optional

扩展字段

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

fromNick

String

optional

发送方的昵称

done

结果回调函数

Returns:

Type

Description

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

sendFile(options){Void|Message}

发送文件消息

文件消息是消息类型的一种

开发者可以直接发送文件消息支持以下几种场景通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件

通过参数blob传入 Blob 对象

通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL

SDK会先将文件上传到文件服务器, 然后把拿到的文件对象在uploaddone回调中传给用户, 然后将其拼装成文件消息发送出去。

开发者也可以先预览文件来获取文件对象, 然后调用此接口发送文件消息。通过参数file传入文件

直接发送文件消息的话会在beforesend回调里面传入SDK生成的idClient, 如果先预览文件再发送, 那么此接口会直接返回idClient

参数type指定了要发送的文件类型, 包括图片、音频、视频和普通文件, 对应的值分别为'image'、'audio'、'video'和'file', 不传默认为'file'。

图片、音频、视频和普通文件的区别在于具体的文件信息不一样, 具体字段请参考

文件大小限制为最大100M高级浏览器会在上传前就检测文件大小

IE8和IE9会在上传完成后检测文件大小

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

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

文件对象, 开发者可以通过预览文件拿到文件对象

resend

Boolean

false

optional

是否是重发

beginupload

function

optional

开始上传图片的回调

如果开发者传入 fileInput, 在此回调之前不能修改 fileInput

在此回调之后可以取消图片上传, 此回调会接收一个参数 upload, 调用 upload.abort(); 来取消文件上传

uploadprogress

optional

上传进度, IE9以下不支持上传进度

uploaddone

optional

上传完成回调

beforesend

optional

发送文件消息之前的回调函数

resend

Boolean

optional

是否是重发

idClient

String

optional

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

custom

String

optional

扩展字段

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

fromNick

String

optional

发送方的昵称

done

结果回调函数

Returns:

Type

Description

Void

|

Message

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

如果提供了参数file, 那么直接发送文件消息, 返回消息

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

});See:

sendGeo(options)

发送地理位置消息

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

geo

Object

地理位置对象

Name

Type

Description

lng

Number

经度

lat

Number

纬度

title

String

地址描述

resend

Boolean

optional

是否是重发

idClient

String

optional

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

custom

String

optional

扩展字段

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

Returns:

Type

Description

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

sendText(options)

发送文本消息

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

text

String

文本消息内容

resend

Boolean

optional

是否是重发

idClient

String

optional

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

custom

String

optional

扩展字段

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

done

结果回调函数

Returns:

Type

Description

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

}See:

sendTipMsg(options)

发送提醒消息

提醒消息是消息类型的一种

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

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

tip

String

提醒内容

resend

Boolean

optional

是否是重发

idClient

String

optional

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

custom

String

optional

扩展字段

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

Returns:

Type

Description

Example:

var msg = chatroom.sendTipMsg({

scene: 'p2p',

to: 'account',

tip: 'tip content',

done: sendChatroomMsgDone

});

console.log('正在发送聊天室提醒消息, id=' + msg.idClient);See:

setOptions(options)

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

token

String

帐号的 token, 用于建立连接

Example:

// 更新 token 的例子

chatroom.setOptions({

token: 'newToken'

});

updateChatroomMemberTempMute(options){Void}

Params:

Name

Type

Description

options

Object

配置参数

Name

Type

Description

account

String

帐号

duration

Number

禁言时长，单位秒，传0表示解除禁言

needNotify

Boolean

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

custom

String

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

Returns:

Type

Description

Void

Example:

chatroom.updateChatroomMemberTempMute({

account: 'account',

duration: 60,

needNotify: true,

custom: 'biu',

done: updateChatroomMemberTempMuteDone

})

function updateChatroomMemberTempMuteDone(error, obj) {

console.log('设置聊天室临时禁言' + (!error?'成功':'失败'), error, obj);

}