跳到主要内容
版本：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是失败回调

代码示例

JavaScript
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是失败回调

代码示例

JavaScript
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是失败回调

代码示例

JavaScript
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标签创建的时间戳

代码示例

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

用户标签多端同步​

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

代码示例

JavaScript
/**
* 设置会话标签更改时的回调
* 当用户在其它端添加移除更新标签时会触发此监听器，用于多端之间的信息同步。
* 收到此回调，可调用 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

代码示例

JavaScript
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

代码示例

JavaScript
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

代码示例

JavaScript
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是否置顶

代码示例

JavaScript
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是失败回调

代码示例

JavaScript
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获取未读消息数

代码示例

JavaScript
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

代码示例

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

用户会话标签多端同步​

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

代码示例

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