聊天室 - IM 即时通讯

IM 即时通讯

不含 UI 集成

开发者中心

IM 即时通讯

不含 UI 集成

聊天室

更新时间： 2023/02/06 15:53:01

请查阅集成方式来下载并引入 SDK 文件

聊天室功能概述

目前不支持通过 SDK 接口建立/解散聊天室。
进入聊天室时必须建立新的连接，退出聊天室或者被踢会断开连接，在聊天室中掉线会有自动重连，开发者需要监听聊天室连接状态来做出正确的界面表现。
支持聊天人数无上限。
聊天室只允许用户手动进入，无法进行邀请。
支持同时进入多个聊天室，会建立多个连接。
断开聊天室连接后，服务器不会再推送该聊天室的消息给此用户。
在进行一切操作之前，必须先进入聊天室。即必须先初始化好聊天室并且收到onconnect回调。
用户进入聊天室之后，不会收到此聊天室的历史消息推送。如有历史消息需求，可以调用消息查询接口进行显示。
聊天室成员分固定成员和游客两种类型。

进入聊天室

获取聊天室服务器地址

初始化聊天室之前要先获取聊天室服务器地址, 有两种方式

如果开发者有 NIM 的实例, 那么可以直接从 IM 连接上获取聊天室服务器地址, 示例代码如下

nim.getChatroomAddress({
  chatroomId: 'chatroomId',
  done: getChatroomAddressDone
});
function getChatroomAddressDone(error, obj) {
  console.log('获取聊天室地址' + (!error?'成功':'失败'), error, obj);
}

如果开发者没有 NIM 的实例, 那么需要从服务器获取聊天室服务器地址, 请参考 demo 来查看具体的做法

初始化聊天室

初始化聊天室之前，必须拿到聊天室服务器地址
此接口为单例模式, 对于同一个账号, 永远返回同一份实例, 即只有第一次调用会初始化一个实例
后续调用此接口会直接返回初始化过的实例, 同时也会调用接口更新聊天室配置更新传入的配置
后续调用此接口时, 如果连接已断开, 会自动建立连接
当发生掉线时，SDK会自动进行重连
在收到onconnect回调之后说明成功进入聊天室, 此时可以进行其他的聊天室操作了.
匿名登录聊天室
- SDK支持用户以游客身份访问聊天室，即通过配置参数 isAnonymous: true实现
- 第一次使用匿名方式登录聊天室时（新建实例），无需填写account参数，但需要在登录以后从chatroom实例中获取SDK生成的该参数
- 使用匿名方式登录聊天室，必须填写用户昵称（非匿名方式为选填），建议填写头像
- 为防止聊天室不断的被创建新实例，建议用户需要更新聊天室配置时（匿名模式），在update或第二次getInstance时，将前一次获取的account通过参数传入

示例代码

// 注意这里, 引入的 SDK 文件不一样的话, 你可能需要使用 SDK.Chatroom.getInstance 来调用接口
// 非匿名方式登录
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
  //用户标签更新
  `onTagsUpdate`: onChatroomTags
});
function onChatroomConnect(obj) {
  console.log('进入聊天室', obj);
  // 连接成功后才可以发消息
  var msg = chatroom.sendText({
    text: 'hello',
    done: function sendChatroomMsgDone (msgObj) {
    }
  })
}
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);
}
function onChatroomTags(Tags) {
  console.log('收到更新的标签', tags);
}

// 匿名方式登录
var chatroom = Chatroom.getInstance({
  appKey: 'appKey',
  // account: 不需要填account
  // token: 不需要填account
  chatroomId: 'chatroomId',
  chatroomAddresses: [
    'address1',
    'address2'
  ],
  chatroomNick: 'chatroomNick',
  chatroomAvatar: 'chatroomAvatar',
  isAnonymous: true,
  onconnect: onChatroomConnect,
  // ...
});

function onChatroomConnect (obj) {
  // 该处chatroom为全局生成的实例
  window.account = chatroom.account
}

参数解释

appKey: 在云信管理后台查看应用的 appKey
account: 帐号, 应用内唯一
token: 帐号的 token, 用于建立连接
nosScene nos存储场景默认chatroom
nosSurvivalTime nos存储场景有效时间默认Infinity
chatroomId: 聊天室 id
chatroomAddresses: 聊天室地址列表
chatroomNick: 进入聊天室后展示的昵称, 如果不设置并且托管了用户资料, 那么使用用户资料里面的昵称
chatroomAvatar: 进入聊天室后展示的头像, 如果不设置并且托管了用户资料, 那么使用用户资料里面的头像
chatroomCustom: 扩展字段, 设置了之后, 通过获取聊天室成员列表获取的聊天室成员信息会包含此字段
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
chatroomEnterCustom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
onconnect: 连接建立后的回调, 会传入聊天室信息
onwillreconnect: 即将重连的回调
- 此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
- 此回调会收到一个对象, 包含额外的信息, 有以下字段
  - duration: 距离下次重连的时间
  - retryCount: 重连尝试的次数
ondisconnect: 断开连接后的回调
- 此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
- 此回调会收到一个对象, 包含错误的信息, 有以下字段
  - code: 出错时的错误码, 可能为空
    - 302: 账号或者密码错误
    - 'kicked': 被踢
- 当code为'kicked'的时候, 此对象会有以下字段
  - reason: 被踢的原因
    - chatroomClosed: 聊天室关闭了
    - managerKick: 被管理员踢出
    - samePlatformKick: 不允许同一个帐号重复登录同一个聊天室
  - message: 文字描述的被踢的原因
onerror: 发生错误的回调, 会传入错误对象
onmsgs: 收到消息的回调, 会传入聊天室消息对象数组
onTagsUpdate：用户标签更新的回调,会传入变更后的标签信息

多端登录

支持设置聊天室多端登录策略，即当同账号在不同客户端登录时，是否可以同时进入同一个聊天室。可以进入云信控制台选择应用 > IM专业版 > 功能配置 > 聊天室配置 > 聊天室多端登录配置进行设置。

只允许一端登录，Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时，新设备会将旧设备踢下线。
各端均可以同时登录在线。最多可支持10个设备同时在线，在设备数上限内，所有的新设备再次登录，均不会将在线的旧设备踢下线。

控制台修改多端互踢的逻辑之后，下次新的设备登录时才会基于新的多端互踢策略进行校验，已经建立连接的设备不会因为策略的修改被强制踢出。

如果某台设备重复登录同一个聊天室，后登录的会将前面的长连接断开，此时会再触发一次进入聊天室的抄送，但是不会触发退出聊天室的抄送。关于进出聊天室（eventType=9）的抄送请参见聊天室事件抄送。

退出聊天室

初始化聊天室并收到onconnect回调之后, 表明进入了聊天室
在收到onconnect回调后可以调用chatroom.disconnect();来退出聊天室
退出聊天室后可以调用chatroom.connect();来重新进入聊天室

切换聊天室

如果需要切换聊天室, 操作步骤如下

调用退出聊天室来退出聊天室
调用初始化聊天室来初始化新的聊天室

更新聊天室配置

聊天室设计为单例模式, 如果需要更新当前聊天室的配置, 那么可以调用此接口, 参数列表和格式跟Chatroom.getInstance保持一致, 以更新 token 为例

// 断开聊天室
chatroom.disconnect()
// 更新 token
chatroom.setOptions({
  token: 'newToken'
});
// 重新连接
chatroom.connect()

清除聊天室实例

web sdk 连接实例均为单例模式，但可以调用相应接口清除内存中记录的实例，即断开连接，清除内存消息记录及时间戳，方便开发者做到干净重连。

  var chatroom = Chatroom.getInstance({...})
  // 清除实例
  chatroom.destroy({
    done: function (err) {
      console.log('实例已被完全清除')
    }
  })

聊天室信息管理

聊天室的信息对象有以下字段

id: 聊天室 id
name: 聊天室名字
announcement: 聊天室公告
broadcastUrl: 直播地址
custom: 第三方扩展字段
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
createTime: 创建时间
updateTime: 更新时间
creator: 创建者账号
onlineMemberNum: 当前在线人数
mute 是否禁言, 禁言状态下普通成员不能发送消息, 创建者和管理员可以发送消息

获取聊天室信息

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

更新聊天室信息

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

可更新的字段有

chatroom: 聊天室自有属性
- chatroom.name: 聊天室名字
- chatroom.announcement: 聊天室公告
- chatroom.broadcastUrl: 直播地址
- chatroom.custom: 第三方扩展字段
- chatroom.queuelevel 队列管理权限：0:所有人都有权限变更队列，1:只有主播管理员才能操作变更

其他参数:

needNotify 是否需要下发对应的通知消息
custom 对应的通知消息的扩展字段
needSave 可选，默认false，是否支持nick,avator和custom字段的持久化（固定成员有效）
done 更新操作完成的回调

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

聊天室消息的收发

聊天室消息对象

聊天室消息对象有以下字段

chatroomId: 聊天室 ID
idClient: SDK生成的消息id, 在发送消息之后会返回给开发者, 开发者可以在发送消息的结果回调里面根据这个ID来判断相应消息的发送状态, 到底是发送成功了还是发送失败了, 然后根据此状态来更新页面的UI。如果发送失败, 那么可以重新发送此消息
from: 消息发送方, 帐号
fromNick: 消息发送方的昵称
fromAvatar: 消息发送方的头像
fromCustom: 消息发送方的扩展字段
fromClientType: 发送方的设备类型
type: 聊天室消息类型
flow: 消息的流向
- 'in'表示此消息是收到的消息
- 'out'表示此消息是发出的消息
text: 文本消息的文本内容, 请参考发送聊天室文本消息
file: 文件消息的文件对象, 具体字段请参考图片对象、音频对象、视频对象、文件对象, 请参考发送聊天室文件消息
geo: 地理位置消息的地理位置对象, 请参考发送聊天室地理位置消息
tip: 提醒消息的内容, 请参考发送聊天室提醒消息
content: 自定义消息的消息内容, 开发者可以自行扩展, 建议封装成JSON格式字符串, 请参考发送聊天室自定义消息
attach: 聊天室通知消息的附加信息, 参考聊天室通知消息的类型来查看详细解释
custom: 扩展字段
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
resend: 是否是重发的消息
time: 时间戳

聊天室消息类型

'text' (文本)
'image' (图片)
'audio' (音频)
'video' (视频)
'file' (文件)
'geo' (地理位置)
'custom' (自定义消息)
'tip' (提醒消息)
- 提醒消息用于会话内的状态提醒，如进入会话时出现的欢迎消息，或者会话命中敏感词后的提示消息等等.
'notification' (聊天室通知消息)
- 某些聊天室操作后所有聊天室成员会收到一条相应的聊天室通知消息, 详细介绍请参考聊天室通知消息的类型

聊天室通知消息的类型

聊天室通知消息是聊天室消息的一种, 请参考聊天室消息类型, 某些聊天室操作后所有聊天室成员会收到一条相应的聊天室通知消息
聊天室通知消息有一个字段attach包含了额外的信息, attach有一个字段type来标识聊天室通知消息的类型
- memberEnter
  - 当有人进入聊天室时, 所有聊天室成员会收到类型为'memberEnter'的聊天室通知消息。
- memberExit
  - 当有人退出聊天室时, 所有聊天室成员会收到类型为'memberExit'的聊天室通知消息。
- addManager
  - 当有人被加为管理员时, 所有聊天室成员会收到类型为'addManager'的聊天室通知消息。
- removeManager
  - 当有人被移除管理员时, 所有聊天室成员会收到类型为'removeManager'的聊天室通知消息。
- addCommon
  - 当有人被加为普通成员时, 所有聊天室成员会收到类型为'addCommon'的聊天室通知消息。
- removeCommon
  - 当有人被移除普通成员时, 所有聊天室成员会收到类型为'removeCommon'的聊天室通知消息。
- blackMember
  - 当有人被加入黑名单时, 所有聊天室成员会收到类型为'blackMember'的聊天室通知消息。
- unblackMember
  - 当有人被移除黑名单时, 所有聊天室成员会收到类型为'unblackMember'的聊天室通知消息。
- gagMember
  - 当有人被加入禁言名单时, 所有聊天室成员会收到类型为'gagMember'的聊天室通知消息。
- ungagMember
  - 当有人被移除禁言名单时, 所有聊天室成员会收到类型为'ungagMember'的聊天室通知消息。
- kickMember
  - 当有人被踢出聊天室时, 所有聊天室成员会收到类型为'kickMember'的聊天室通知消息。
- updateChatroom
  - 当更新聊天室信息时, 所有聊天室成员会收到类型为'updateChatroom'的聊天室通知消息。
- updateMemberInfo
  - 当更新自己在聊天室内的信息时, 所有聊天室成员会收到类型为'updateMemberInfo'的聊天室通知消息。
- addTempMute
- removeTempMute
  - 当有人被设置聊天室临时禁言时，所有聊天室成员会收到类型为'addTempMute' or 'removeTempMute'的聊天室通知消息。
- muteRoom 聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
- unmuteRoom 聊天室解除全体禁言状态
attach的字段from为操作方的账号, fromNick为操作方的昵称, to为被操作方的账号, toNick为被操作方的昵称
- 如果是addTempMute, attach的字段duration代表本次禁言的时长
- 如果是removeTempMute, attach的字段duration代表解禁提前的时长

发送聊天室消息

包括以下接口

为保证用户体验（如避免服务器过载），目前针对消息接收，有两套流控机制。第一套针对普通消息，聊天室用户每秒至多可接收20条，超过部分会因为流控随机丢弃。第二套针对高优先级消息，每秒至多接收10条，超过部分无法保证不丢失。
为避免丢失重要消息（通常为服务端消息），可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息，进而保证高优先级消息流控上限内（每秒10条）的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。
1秒内默认最多可调用发送聊天室消息接口100次。如需上调上限，请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

发送聊天室文本消息

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

预览聊天室文件

开发者可以预览文件, 支持以下几种场景
- 通过参数fileInput传入文件选择 dom 节点或者节点 ID
- 通过参数blob传入 Blob 对象
- 通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL, 此用法需要浏览器支持 window.Blob
SDK会将文件上传到文件服务器, 然后将拿到的文件对象在done回调中传给开发者, 文件对象有以下几种
开发者在拿到文件对象之后, 可以调用发送聊天室文件消息来发送文件消息。
文件大小限制为最大100M
- 高级浏览器会在上传前就检测文件大小
- IE8/IE9 会在上传完成后检测文件大小(5.0.0以下版本支持IE8)

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

发送聊天室文件消息

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

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

发送聊天室地理位置消息

地理位置消息是聊天室消息的一种, geo参数请参考地理位置对象

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

发送聊天室提醒消息

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

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

发送聊天室自定义消息

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

发送聊天室消息的配置选项

上面的各个发送消息的接口都可以配置额外的选项, 来满足开发者对服务器的自定义需求。
- custom: 扩展字段
  - 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
- skipHistory: 是否跳过云端存储，拉取历史消息的时候不会包含这条消息
- yidunEnable: 指定是否需要使用自定义反垃圾字段，即antiSpamContent，默认false不需要。
- antiSpamUsingYidun: 单条消息是否使用易盾反垃圾，false表示开通易盾的情况下，不过易盾反垃圾。
- antiSpamContent: 在开启yidunEnable后, 开发者自定义的反垃圾字段（json格式)，格式如下：{"type": 1, "data": "custom content"} 字段说明：type:1.文本，2.图片，3视频，data内容:文本内容or图片地址or视频地址
下面给一个发送文本消息的例子, 发送其它消息的接口类似

var msg = chatroom.sendText({
  text: 'hello',
  custom: '{}',
  done: sendChatroomMsgDone
});
console.log('正在发送聊天室text消息, id=' + msg.idClient);

设置聊天室消息扩展字段

调用发送聊天室消息的方法时，构造的聊天室消息对象中，custom字段即表示聊天室消息的服务端扩展字段。

聊天室消息没有客户端扩展字段。
扩展字段，请使用JSON格式封装，并传入非格式化的JSON字符串，最大长度1024字节。

查询云端历史消息

获取聊天室历史消息

timetag 获取从 timetag 对应的时间点往前的若干条数据
不填 timetag 的话默认为服务器当前时间
limit 不填的话默认 100 条
reverse: 默认false表示从timetag开始往前查找历史消息; true表示从timetag开始往后查找历史消息
msgTypes 类型为字符串或数组，可选择获取历史消息的消息类型，不填则不区分类型，获取全部消息
- text 过滤筛选文本消息
- image 过滤筛选图片消息
- audio 过滤筛选语音消息
- video 过滤筛选视频消息
- geo 过滤筛选地理位置消息
- notification 过滤筛选通知消息
- file 过滤筛选文件消息
- tip 过滤筛选提醒消息
- custom 过滤筛选自定义消息

chatroom.getHistoryMsgs({
  timetag: 1451393192478,
  limit: 100,
  msgTypes: ['text', 'image'],
  done: getHistoryMsgsDone
})

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

根据标签查询历史消息

根据标签（Tags）在云端查询聊天室的历史消息。

以 fromTime 和 toTime（单位毫秒）为时间戳，选择查询方向，指定一种或多种标签和消息类型，往前或者往后拉取 limit 条消息。

参数说明

参数	类型	说明
tags	stringArray	标签列表，支持传入多个标签同时查询
types	stringArray	消息类型列表，查询指定消息类型的消息，默认查询全部消息类型
fromTime	number	起始时间，时间戳
toTime	number	结束时间，时间戳
limit	number	可查询的最大消息数量，默认和最大值都为 100
reverse	number	是否反向
done	function	回调成功

示例

// IM1 根据标签获取历史消息
chatroom.getHistoryMsgsByTags({
  "tags": ["aaa"],
  done: function(err, obj, content) { if(!err) { console.log('msgs: ', content)} }
})

聊天室成员管理

聊天室成员概述

聊天室成员对象有以下字段

chatroomId: 聊天室 ID
account: 账号
nick: 聊天室内的昵称
avatar: 聊天室内的头像
type: 聊天室成员类型
guest 是否是游客
blacked 是否被拉黑
gaged 是否被禁言
level: 级别
online: 是否在线, 只有固定成员才能离线, 对游客而言只能是在线
enterTime: 进入聊天室的时间, 如果离线, 无该字段
custom: 扩展字段
- 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
updateTime: 更新时间
tempMuted: 是否被临时禁言
tempMuteDuration: 临时禁言剩余时长

聊天室成员类型 type 分为固定成员和游客两种。固定成员又分为房主、管理员、普通成员和受限成员四种。禁言用户和拉黑用户都属于受限用户。

'owner' (房主)
'manager' (管理员)
'restricted' (受限制, 被拉黑或者禁言)
'common' (普通成员)
'guest' (游客)

获取聊天室成员列表

guest: true表示获取游客, false表示获取非游客成员
- 游客列表按照游客进入聊天室的时间倒序排列
- 非游客（即固定成员）列表按照成为固定成员的时间倒序排列
当设置guest=false来获取非游客成员时, 默认会获取所有的固定成员, 包括不在线的, 可以设置onlyOnline=true来只获取在线的固定成员
time 分页用, 查找该时间戳之前的成员
- 默认 0 代表当前服务器时间
- 获取游客时, 此字段填上次获取的最后一个游客的enterTime
- 获取非游客时, 此字段填上次获取的最后一个非游客的updateTime
limit 分页用, 默认 100

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

获取聊天室成员信息

accounts: 待查询的账号列表, 每次最多20个

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

修改自身信息

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

可更新的字段有

'nick' 聊天室内的昵称
'avatar' 聊天室内的头像
'custom': 第三方扩展字段

  chatroom.updateMyChatroomMemberInfo({
    member: {
    nick: 'newNick',
    avatar: 'newAvatar',
    custom: 'newCustom',
    },
    needNotify: true,
    custom: 'biu',
    done: updateMyChatroomMemberInfoDone
  })

  function updateMyChatroomMemberInfoDone (error, obj) {
    console.log('更新自己在聊天室内的信息' + (!error?'成功':'失败'), error, obj);
  }

设置聊天室成员

包括以下接口

设置聊天室管理员

管理员可以设置聊天室普通成员, 设置聊天室黑名单, 设置聊天室禁言名单, 踢聊天室成员
account: 待设置的账号
isAdd: true表示添加, false表示移除
- 当有人被加为管理员时, 所有聊天室成员会收到类型为'addManager'的聊天室通知消息。
- 当有人被移除管理员时, 所有聊天室成员会收到类型为'removeManager'的聊天室通知消息。
custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃

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

设置聊天室普通成员

account: 待设置的账号
isAdd: 是否加为普通成员
- 当有人被加为普通成员时, 所有聊天室成员会收到类型为'addCommon'的聊天室通知消息。
- 当有人被移除普通成员时, 所有聊天室成员会收到类型为'removeCommon'的聊天室通知消息。
level: 等级
custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃

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

设置聊天室黑名单

被加入黑名单的人将不能进入此聊天室
account: 待设置的账号
isAdd: true表示添加, false表示移除
- 当有人被加入黑名单时, 所有聊天室成员会收到类型为'blackMember'的聊天室通知消息。
- 当有人被移除黑名单时, 所有聊天室成员会收到类型为'blackMember'的聊天室通知消息。
custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃

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

设置聊天室禁言名单

被加入禁言名单的人将不能在该聊天室发送消息
account: 待设置的账号
isAdd: true表示添加, false表示移除
- 当有人被加入禁言名单时, 所有聊天室成员会收到类型为'gagMember'的聊天室通知消息。
- 当有人被移除禁言名单时, 所有聊天室成员会收到类型为'ungagMember'的聊天室通知消息。
custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃

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

设置聊天室临时禁言

当有人被设置聊天室临时禁言时，所有聊天室成员会收到类型为'addTempMute' or 'removeTempMute'的聊天室通知消息。
account: 帐号
duration: 禁言时长，单位秒，传0表示解除禁言
needNotify: 是否需要下发对应的通知消息
custom: 对应的通知消息的扩展字段

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

踢聊天室成员

account: 待踢的账号
custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段, 被踢的人收到的ondisconnect回调接收的参数的custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
当有人被踢出聊天室时, 所有聊天室成员会收到类型为'kickMember'的聊天室通知消息。

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

聊天室队列服务

聊天室队列中添加元素

方法名：queueOffer
参数：
- elementKey: string类型，元素键名
- elementValue: string类型，元素内容
- transient: boolean类型，帐号从聊天室中离开/掉线后，其添加的元素是否被删除
- done: 执行完成的回调函数，第一个参数为error
示例：

  chatroom.queueOffer({
    elementKey: `account`,
    elementValue: JSON.stringify({
      nick: `nickname`,
      webrtc: 1
    }),
    transient: true,
    done (err, obj, content) {
      if (err) {
        console.error(err)
      }
    }
  })

聊天室队列中删除元素

方法名：queuePoll，传空取第一个元素
参数：
- elementKey: string类型，需要删除的元素键名
- done: 执行完成的回调函数，第一个参数为error
示例：

  chatroom.queuePoll({
    elementKey: `account`,
    done (err, obj, content) {
      if (err) {
        console.error(err)
      }
    }
  })

聊天室队列中获取列表

方法名：queueList
参数：
- done: 执行完成的回调函数，第一个参数为error，第三个参数为返回的结果
示例：

  chatroom.queueList({
    done (err, obj, content) {
    if (err) {
      console.error(err)
    }
    console.log(content)
    if (content && content.queueList) {
      queueCount = 0
      for (let i = 0; i < content.queueList.length; i++) {
        let queue = content.queueList[i]
        console.log(queue)
        queueCount++
      }
    }
    }
  })

聊天室队列批量更新

若该元素由用户A添加，之后再由用户B更新，则该元素的所有者为用户B。

方法名：queueChange
参数：
- elementMap: object类型，批量更新元素的key-value对，分别是elementKey和elementValue（elementKey限制128字节,elementValue限制4096字节），一次最多更新100个
- needNotify: boolean类型，是否需要发送广播通知
- notifyExt: string类型，通知中的自定义字段，长度限制2048
- done: 执行完成的回调函数，第一个参数为error，第二个是传入参数，第三个参数为返回的结果(不存在的元素elementKey列表）
示例：

  chatroom.queueChange({
    elementMap: {
      elementKey1: elementValue2,
      elementKey3: elementValue4,
    },
    needNotify: true,
    notifyExt: '批量更新队列',
    done (err, obj, content) {
      if (err) {
        console.error(err)
      }
    }
  })

聊天室队列中查看第一个元素

方法名：peak
参数：
- done: 执行完成的回调函数，第一个参数为error，第三个参数为返回的结果
示例：

  chatroom.peak({
    done (err, obj, content) {
    if (err) {
      console.error(err)
    }
    console.log(content)
    }
  })

清除聊天室队列

方法名：drop
参数：
- done: 执行完成的回调函数，第一个参数为error
示例：

  chatroom.drop({
    done (err, obj, content) {
    if (err) {
    console.error(err)
    }
    }
  })

聊天室队列通知

聊天室队列的变更会在聊天室通知消息中下发

function onChatroomMsgs (msgs) {
  let self = this
  msgs.forEach(msg => {
    if (msg.type === 'notification') {
      let attach = msg.attach
      let qc = attach.queueChange || {}
      switch (attach.type) {
        case 'updateQueue':
          if (qc.type === 'OFFER') {
            console.log(qc)
          } else if (qc.type === 'POLL') {
            console.log(qc)
          } else if (qc.type === 'DROP') {
            console.log(qc)
          } else if (qc.type === 'PARTCLEAR') {
            console.log(qc)
          }
          break
        case 'batchUpdateQueue':
          console.log(qc)
        }
        break
    }
  })
}

聊天室定向消息

在sendText方法添加toAccids参数指定发送给指定账号，该参数是一个字符串数组，一次最多100个账号，超过则发送不成功，为空则为广播消息，如果有该参数则会忽略标签和空间坐标，该类型消息对接收方隐藏，接收方无法区分收到的是否为定向消息

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

此文档是否对你有帮助？

有帮助

我要吐槽

文档反馈

在线咨询

聊天室功能概述
进入聊天室
获取聊天室服务器地址
初始化聊天室
多端登录
退出聊天室
切换聊天室
更新聊天室配置
清除聊天室实例
聊天室信息管理
获取聊天室信息
更新聊天室信息
聊天室消息的收发
聊天室消息对象
聊天室消息类型
聊天室通知消息的类型
发送聊天室消息
发送聊天室文本消息
预览聊天室文件
发送聊天室文件消息
发送聊天室地理位置消息
发送聊天室提醒消息
发送聊天室自定义消息
发送聊天室消息的配置选项
设置聊天室消息扩展字段
查询云端历史消息
获取聊天室历史消息
根据标签查询历史消息
聊天室成员管理
聊天室成员概述
获取聊天室成员列表
获取聊天室成员信息
修改自身信息
设置聊天室成员
踢聊天室成员
聊天室队列服务
聊天室队列中添加元素
聊天室队列中删除元素
聊天室队列中获取列表
聊天室队列批量更新
聊天室队列中查看第一个元素
清除聊天室队列
聊天室队列通知
聊天室定向消息