跳到主要内容
版本:2.X

会话标签

SDK 2.X 版本从 2.8.0 开始支持会话标签功能。

会话标签用于对会话进行分组。用户可设置会话标签,用于会话的分组显示。

每个用户最多可以创建 20 个标签,每个标签下最多可以添加 1000 个会话。同一个会话可以设置多个不同的标签。

管理标签

SDK 支持创建标签、编辑标签,获取标签列表,以及移除标签。SDK 创建的标签可用于对会话进行管理。

SDK 创建的标签会被同步到服务端。

关于如何使用标签管理会话,详见使用标签管理会话

创建标签

每个用户最多可以创建 20 个标签。

API 参考:createTag

参数说明

参数类型必填说明
tagObject标签信息
tag.tagIdString标签 Id,标签唯一标识,长度不超过 10 个字
tag.tagNameString标签名称,长度不超过 15 个字
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

代码示例

var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('创建标签成功')
},
onError: function(error) {
console.log('创建标签失败', error)
}
}
RongIMClient.getInstance().createTag(tag,callback)

移除标签

API 参考:removeTag

参数说明

参数类型必填说明
tagIdString标签 Id
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

代码示例

var tagId = '<标签Id>'
var callback = {
onSuccess: function() {
console.log('删除标签成功')
},
onError: function(error) {
console.log('删除标签失败', error)
}
}
RongIMClient.getInstance().removeTag(tagId,callback)

编辑标签

参数说明

参数类型必填说明
tagObject标签信息
tag.tagIdString标签 Id,标签唯一标识,长度不超过 10 个字
tag.tagNameString标签名称,长度不超过 15 个字
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

代码示例

var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('编辑标签成功')
},
onError: function(error) {
console.log('编辑标签失败', error)
}
}
RongIMClient.getInstance().updateTag(tag,callback)

获取标签列表

API 参考:getTagList

参数说明

参数类型必填说明
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

成功回调

成功回调 ITagInfo[] 的参数说明:

参数返回类型说明
tagInfoITagInfo[]标签列表信息,详见下方 ITagInfo 属性说明
  • ITagInfo 属性说明

    参数类型说明
    tagIdString标签 Id
    tagNameString标签名称
    conversationCountNumber标签下的会话数量
    createdTimeNumber标签创建的时间戳

代码示例

var callback = {
onSuccess: function(tagInfo) {
console.log(tagInfo)
console.log('获取标签列表成功')
},
onError: function(error) {
console.log('获取标签列表失败', error)
}
}
RongIMClient.getInstance().getTagList(callback)

用户标签多端同步

该回调不会给当前操作设备回调,只会给其他的多端设备回调。

代码示例

/**
* 设置会话标签更改时的回调
* 当用户在其它端添加移除更新标签时会触发此监听器,用于多端之间的信息同步。
* 收到此回调,可调用 getTagList 获取最新标签信息
* 请在初始化之后,连接之前调用该方法
*/
var tagListener = {
onChanged:function(){
return
}
}
RongIMClient.setTagListener(tagListener)

使用标签管理会话

SDK 支持使用一个或多个标签标记会话,可用于会话的分组显示、获取会话列表等操作,并提供了多个接口用于移除会话上的标签。

会话标签还支持一系列高级功能,包括按照标签获取会话列表、按照标签获取标签下所有会话的消息未读数,以及在特定标签下设置某个会话置顶。

添加会话到一个标签

每个标签下最多可以添加 1000 个会话。

API 参考:addTagForConversations

参数说明

参数类型必填说明
tagIdString标签信息
conversationsIConversationOption []要添加的会话列表。详见下方 IConversationOption 属性说明
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调
  • IConversationOption 属性说明

    参数类型必填说明
    typeNumber会话类型
    targetIdString目标 ID

代码示例

var tag = {
tagId: '<标签Id>',
tagName: '<新的标签名字>'
}
var callback = {
onSuccess: function() {
console.log('添加成功')
},
onError: function(error) {
console.log('添加失败', error)
}
}
var conversations =[{
type:1,//会话类型
targetId:'<目标Id>'
}
]
RongIMClient.getInstance().addTagForConversations(tagId,conversations,callback)

删除指定标签中某些会话

removeTagForConversations 接口可从特定标签下移除指定多个会话,也可以理解为“为多个会话移除单个标签”。

API 参考:removeTagForConversations

参数说明

参数类型必填说明
tagIdString标签 Id
conversationsIConversationOption []要从指定标签下删除的会话列表。详见下方 IConversationOption 属性说明
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调
  • IConversationOption 属性说明

    参数类型必填说明
    typeNumber会话类型
    targetIdString目标 ID

代码示例

var tagId = '<标签Id>'
var callback = {
onSuccess: function() {
console.log('删除成功')
},
onError: function(error) {
console.log('删除失败', error)
}
}
var conversations =[{
type:1,//会话类型
targetId:'<目标Id>'
}]
RongIMClient.getInstance().removeTagForConversations(tagId,conversations,callback)

删除指定会话中的某些标签

removeTagsForConversation 接口可为特定会话移除指定的一个或多个标签。

API 参考:removeTagsForConversation

参数说明

参数类型必填说明
conversationIConversationOption会话。详见下方 IConversationOption 属性说明
tagIdsArray所有标签
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调
  • IConversationOption 属性说明

    参数类型必填说明
    typeNumber会话类型
    targetIdString目标 ID

代码示例

var tagIds = ['<标签Id>']
var callback = {
onSuccess: function() {
console.log('删除成功')
},
onError: function(error) {
console.log('删除失败', error)
}
}
var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
RongIMClient.getInstance().removeTagsForConversation(conversation,tagIds,callback)

获取指定会话下的所有标签

API 参考:getTagsForConversation

参数说明

参数类型必填说明
conversationIConversationOption会话。详见下方 IConversationOption 属性说明
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调
  • IConversationOption 属性说明

    参数类型必填说明
    typeNumber会话类型
    targetIdString目标 ID

成功回调

成功回调 IConversationTag 的参数说明:

参数返回类型说明
tagIdString标签 Id
tagNameString标签名称
createdTimeNumber标签创建的时间戳
isTopBoolean是否置顶

代码示例

var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
var callback = {
onSuccess: function(IConversationTag) {
console.log('获取成功',IConversationTag)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getTagsForConversation(conversation,callback)

分页获取指定标签下的会话列表

getConversationListByTag 可从服务端分页获取会话列表,并返回分页查询结果中带有指定标签的会话。

API 参考:getConversationListByTag

参数说明

参数类型必填说明
tagIdString标签 Id
countNumber单次分页查询时需要从服务端获取的会话数量
startTimeNumber会话中最后一条消息时间戳
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

代码示例

var tagId = '<标签Id>'
var count = 10
var startTime = 1649404018538
var callback = {
onSuccess: function(IV2ConversationContainTag) {
console.log('获取成功后会话列表',IV2ConversationContainTag)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getConversationListByTag(tagId,count,startTime,callback)

按标签获取未读消息数

API 参考:getUnreadCountByTag

参数说明

参数类型必填说明
tagIdString标签 Id
containMutedNumber是否包含已设置为免打扰状态的会话
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调

成功回调

成功回调参数说明:

参数返回类型说明
countNumber获取未读消息数

代码示例

var tagId = '<标签Id>'
var containMuted = true
var callback = {
onSuccess: function(count) {
console.log('成功获取未读消息数',count)
},
onError: function(error) {
console.log('获取失败', error)
}
}
RongIMClient.getInstance().getUnreadCountByTag(tagId,containMuted,callback)

设置标签中会话置顶

setConversationStatusInTag 可设置会话在标签下为置顶状态。

设置成功后,可在分页获取指定标签下会话列表(getConversationListByTag)返回的结果中查看相关属性。

  • 注意,setConversationStatusInTag 接口仅用于在特定标签下会话是否置顶。
  • 如需设置会话在会话列表中置顶,请使用 setConversationStatus 接口(SDK ≧ 2.5.8)。

API 参考:setConversationStatusInTag

参数说明

参数类型必填说明
tagIdString标签 Id
conversationIConversationOption会话。详见下方 IConversationOption 属性说明
statusObject置顶状态
status.isTopBoolean是否置顶
callbackObject回调对象
callback.onSuccessFunction成功回调
callback.onErrorFunction失败回调
  • IConversationOption 属性说明

    参数类型必填说明
    typeNumber会话类型
    targetIdString目标 ID

代码示例

var tagId = '<标签Id>'
var conversation ={
type:1,//会话类型
targetId:'<目标Id>'
}
let status = {
isTop:true
}
var callback = {
onSuccess: function() {
console.log('设置成功')
},
onError: function(error) {
console.log('设置失败', error)
}
}
RongIMClient.getInstance().setConversationStatusInTag(tagId,conversation,status,callback)

用户会话标签多端同步

该回调不会给当前操作设备回调,只会给其他的多端设备回调。

代码示例

var tagListener = {
onChanged:function(){
return
}
}
RongIMClient.setConversationTagListener(tagListener)