聊天室管理

更新时间: 2024/07/19 14:43:21

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

聊天室功能概述

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

进入聊天室

获取聊天室服务器地址

初始化聊天室之前要先在服务端获取聊天室服务器地址

初始化聊天室

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

示例代码

javascript// 注意这里, 引入的 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);
}
javascript// 匿名方式登录
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 为例

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

清除聊天室实例

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

javascript  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 是否禁言, 禁言状态下普通成员不能发送消息, 创建者和管理员可以发送消息

获取聊天室信息

javascriptchatroom.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 更新操作完成的回调
javascriptchatroom.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次。如需上调上限,请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

发送聊天室文本消息

javascriptvar 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)
javascriptchatroom.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)
javascriptchatroom.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
});

发送聊天室地理位置消息

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

发送聊天室提醒消息

  • 提醒消息是聊天室消息的一种
  • 提醒消息用于会话内的状态提醒,如进入会话时出现的欢迎消息,或者会话命中敏感词后的提示消息等等.
javascriptvar msg = chatroom.sendTipMsg({
  scene: 'p2p',
  to: 'account',
  tip: 'tip content',
  done: sendChatroomMsgDone
});
console.log('正在发送聊天室提醒消息, id=' + msg.idClient);

发送聊天室自定义消息

javascriptvar 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视频地址
  • 下面给一个发送文本消息的例子, 发送其它消息的接口类似
javascriptvar 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 过滤筛选自定义消息
javascriptchatroom.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
javascriptchatroom.getChatroomMembers({
  guest: false,
  limit: 100,
  done: getChatroomMembersDone
});
function getChatroomMembersDone(error, obj) {
  console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members);
}

获取聊天室成员信息

  • accounts: 待查询的账号列表, 每次最多20个
javascriptchatroom.getChatroomMembersInfo({
  accounts: ['account1', 'account2'],
  done: getChatroomMembersInfoDone
});
function getChatroomMembersInfoDone(error, obj) {
  console.log('获取聊天室成员信息' + (!error?'成功':'失败'), error, obj);
}

修改自身信息

可更新的字段有

  • 'nick' 聊天室内的昵称
  • 'avatar' 聊天室内的头像
  • 'custom': 第三方扩展字段
javascript  chatroom.updateMyChatroomMemberInfo({
    member: {
    nick: 'newNick',
    avatar: 'newAvatar',
    custom: 'newCustom',
    },
    needNotify: true,
    custom: 'biu',
    done: updateMyChatroomMemberInfoDone
  })

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

设置聊天室成员

包括以下接口

设置聊天室管理员
javascriptchatroom.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端会正常接收, 但是会被其它端丢弃
javascriptchatroom.markChatroomCommonMember({
  account: 'account',
  level: 1,
  done: markChatroomCommonMemberDone
});
function markChatroomCommonMemberDone(error) {
  console.log('设置聊天室普通成员' + (!error?'成功':'失败'), error);
}
设置聊天室黑名单
  • 被加入黑名单的人将不能进入此聊天室
  • account: 待设置的账号
  • isAdd: true表示添加, false表示移除
  • custom: 扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息attach.custom的值为此字段
  • 推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
javascriptchatroom.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端会正常接收, 但是会被其它端丢弃
javascriptchatroom.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: 对应的通知消息的扩展字段
javascriptchatroom.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'聊天室通知消息
javascriptchatroom.kickChatroomMember({
  account: 'account',
  done: kickChatroomMemberDone
});
function kickChatroomMemberDone(error, obj) {
  console.log('踢人' + (!error?'成功':'失败'), error, obj);
}

聊天室队列服务

聊天室队列中添加元素

  • 方法名:queueOffer
  • 参数:
    • elementKey: string类型,元素键名
    • elementValue: string类型,元素内容
    • transient: boolean类型,帐号从聊天室中离开/掉线后,其添加的元素是否被删除
    • done: 执行完成的回调函数,第一个参数为error
  • 示例:
javascript  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
  • 示例:
javascript  chatroom.queuePoll({
    elementKey: `account`,
    done (err, obj, content) {
      if (err) {
        console.error(err)
      }
    }
  })

聊天室队列中获取列表

  • 方法名:queueList
  • 参数:
    • done: 执行完成的回调函数,第一个参数为error,第三个参数为返回的结果
  • 示例:
javascript  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列表)
  • 示例:
javascript  chatroom.queueChange({
    elementMap: {
      elementKey1: elementValue2,
      elementKey3: elementValue4,
    },
    needNotify: true,
    notifyExt: '批量更新队列',
    done (err, obj, content) {
      if (err) {
        console.error(err)
      }
    }
  })

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

  • 方法名:peak
  • 参数:
    • done: 执行完成的回调函数,第一个参数为error,第三个参数为返回的结果
  • 示例:
javascript  chatroom.peak({
    done (err, obj, content) {
    if (err) {
      console.error(err)
    }
    console.log(content)
    }
  })

清除聊天室队列

  • 方法名:drop
  • 参数:
    • done: 执行完成的回调函数,第一个参数为error
  • 示例:
javascript  chatroom.drop({
    done (err, obj, content) {
    if (err) {
    console.error(err)
    }
    }
  })

聊天室队列通知

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

javascriptfunction 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个账号,超过则发送不成功,为空则为广播消息,如果有该参数则会忽略标签和空间坐标, 该类型消息对接收方隐藏,接收方无法区分收到的是否为定向消息

javascriptvar 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);
}
此文档是否对你有帮助?
有帮助
去反馈
  • 聊天室功能概述
  • 进入聊天室
  • 获取聊天室服务器地址
  • 初始化聊天室
  • 多端登录
  • 退出聊天室
  • 切换聊天室
  • 更新聊天室配置
  • 清除聊天室实例
  • 聊天室信息管理
  • 获取聊天室信息
  • 更新聊天室信息
  • 聊天室消息的收发
  • 聊天室消息对象
  • 聊天室消息类型
  • 聊天室通知消息的类型
  • 发送聊天室消息
  • 发送聊天室文本消息
  • 预览聊天室文件
  • 发送聊天室文件消息
  • 发送聊天室地理位置消息
  • 发送聊天室提醒消息
  • 发送聊天室自定义消息
  • 发送聊天室消息的配置选项
  • 设置聊天室消息扩展字段
  • 查询云端历史消息
  • 获取聊天室历史消息
  • 根据标签查询历史消息
  • 聊天室成员管理
  • 聊天室成员概述
  • 获取聊天室成员列表
  • 获取聊天室成员信息
  • 修改自身信息
  • 设置聊天室成员
  • 踢聊天室成员
  • 聊天室队列服务
  • 聊天室队列中添加元素
  • 聊天室队列中删除元素
  • 聊天室队列中获取列表
  • 聊天室队列批量更新
  • 聊天室队列中查看第一个元素
  • 清除聊天室队列
  • 聊天室队列通知
  • 聊天室定向消息