IM 即时通讯
Web
产品介绍
简介
主要功能
产品优势
海外数据中心
IM平滑迁移方案
接口及业务限制
功能介绍
帐号集成与登录
基础消息功能
群组功能
聊天室功能
聊天室标签功能
多端登录与互踢策略
质量数据监控台
体验 Demo
下载 SDK 与 Demo 源码
更新日志
IM UIKit 更新日志
NIM SDK 开发版更新日志
NIM SDK 稳定版更新日志
快速开始
跑通 IM Demo 源码
实现 IM 文本消息收发(不含 UI)
含 UI 集成
什么是 IM UIKit
IM UIKit 功能概览
快速集成 IM UIKit
非React框架集成 IM UIKit
组件导入
初始化
全局上下文
登录相关
实现消息收发及界面自定义
集成会话列表界面
集成会话消息界面
集成用户资料组件
集成通讯录界面
集成搜索组件
非 React 框架自定义渲染
主题样式设置
语言设置
初始化(兼容 NIM SDK)
不含 UI 集成
集成 SDK
浏览器环境集成
Node.js集成
初始化与登录相关
初始化与登录 IM
IM 连接相关
多端登录与互踢
消息相关
消息概述
消息收发
消息配置选项
广播消息收发
消息已读回执
消息撤回
消息重发与转发
本地消息
通知消息
群通知消息
超大群通知消息
历史消息
最近会话
用户资料托管
好友关系托管
用户关系托管
在线状态订阅
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
开通聊天室功能
聊天室
反垃圾(内容审核)
域名高可用
融合存储方案
扩展功能
工具方法
最佳实践
聊天室重要消息投递
API参考
SDK API (Web)
IM UIKit Store API
状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
开通聊天室功能
配置应用客户端标识
常见问题
FAQ
服务协议

聊天室

更新时间: 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);
}

初始化聊天室

  • 初始化聊天室之前,必须拿到聊天室服务器地址
  • 此接口为单例模式, 对于同一个账号, 永远返回同一份实例, 即只有第一次调用会初始化一个实例
  • 后续调用此接口会直接返回初始化过的实例, 同时也会调用接口更新聊天室配置更新传入的配置
  • 后续调用此接口时, 如果连接已断开, 会自动建立连接
  • 当发生掉线时,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);
}

更新聊天室信息

可更新的字段有

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

聊天室消息的收发

聊天室消息对象

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

聊天室消息类型

  • 'text' (文本)
  • 'image' (图片)
  • 'audio' (音频)
  • 'video' (视频)
  • 'file' (文件)
  • 'geo' (地理位置)
  • 'custom' (自定义消息)
  • 'tip' (提醒消息)
    • 提醒消息用于会话内的状态提醒,如进入会话时出现的欢迎消息,或者会话命中敏感词后的提示消息等等.
  • 'notification' (聊天室通知消息)

聊天室通知消息的类型

发送聊天室消息

包括以下接口

  • 为保证用户体验(如避免服务器过载),目前针对消息接收,有两套流控机制。第一套针对普通消息,聊天室用户每秒至多可接收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
});

发送聊天室地理位置消息

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

修改自身信息

可更新的字段有

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

设置聊天室成员

包括以下接口

设置聊天室管理员
chatroom.markChatroomManager({
  account: 'account',
  isAdd: true,
  done: markChatroomManagerDone
});
function markChatroomManagerDone(error, obj) {
  console.log('添加聊天室管理员' + (!error?'成功':'失败'), error, obj.member);
}
设置聊天室普通成员
  • account: 待设置的账号
  • isAdd: 是否加为普通成员
  • 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表示移除
  • 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表示移除
  • 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);
}
此文档是否对你有帮助?
有帮助
我要吐槽
  • 聊天室功能概述
  • 进入聊天室
  • 获取聊天室服务器地址
  • 初始化聊天室
  • 多端登录
  • 退出聊天室
  • 切换聊天室
  • 更新聊天室配置
  • 清除聊天室实例
  • 聊天室信息管理
  • 获取聊天室信息
  • 更新聊天室信息
  • 聊天室消息的收发
  • 聊天室消息对象
  • 聊天室消息类型
  • 聊天室通知消息的类型
  • 发送聊天室消息
  • 发送聊天室文本消息
  • 预览聊天室文件
  • 发送聊天室文件消息
  • 发送聊天室地理位置消息
  • 发送聊天室提醒消息
  • 发送聊天室自定义消息
  • 发送聊天室消息的配置选项
  • 设置聊天室消息扩展字段
  • 查询云端历史消息
  • 获取聊天室历史消息
  • 根据标签查询历史消息
  • 聊天室成员管理
  • 聊天室成员概述
  • 获取聊天室成员列表
  • 获取聊天室成员信息
  • 修改自身信息
  • 设置聊天室成员
  • 踢聊天室成员
  • 聊天室队列服务
  • 聊天室队列中添加元素
  • 聊天室队列中删除元素
  • 聊天室队列中获取列表
  • 聊天室队列批量更新
  • 聊天室队列中查看第一个元素
  • 清除聊天室队列
  • 聊天室队列通知
  • 聊天室定向消息