会话标签与分组

按业务维度（例如「工作」「校务」「订单」）把会话挂到标签上：标签增删改查、会话批量挂载/摘除、标签内分页与未读汇总、标签内置顶。标签是服务端状态，多端共享。

契约预留

本平台为 reserved：以下签名来自已冻结绑定，示例为契约样例，不承诺可运行。

平台调用风格

异步风格：Promise<RcResult<T>>（不 reject；错误码在 RcResult.code）；uint64/int64 映射为 number，超出安全整数时由实现改用 string。

接口一览

操作	语义	传输	返回
`createConversationTag`	创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。	REST（客户端）	`ConversationTag`
`updateConversationTag`	重命名会话标签。	REST（客户端）	`ConversationTag`
`deleteConversationTag`	删除会话标签（同时清除标签内会话引用）。	REST（客户端）	`void`
`getConversationTags`	获取全部会话标签（含会话数量）。	REST（客户端）	`ConversationTag[]`
`addConversationsToTag`	把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。	REST（客户端）	`{added:int, existing:int, conversationCount:int}`
`removeConversationsFromTag`	把会话移出标签（≤100/次，幂等）。	REST（客户端）	`{removed:int, conversationCount:int}`
`getConversationsFromTagByPage`	分页获取标签内会话（含置顶/未读数/最后消息时间）。	REST（客户端）	`{total:int, items:ConversationTagConversation[]}`
`getTagsFromConversation`	查询某个会话所属的标签列表。	REST（客户端）	`ConversationTag[]`
`getUnreadCountByTag`	标签内未读汇总（消息总数 + 有未读的会话数）。	REST（客户端）	`{unreadCount:int, unreadConversations:int, conversationCount:int}`
`setConversationToTopInTag`	标签内置顶/取消置顶会话（同步会话会话级置顶状态）。	REST（客户端）	`void`

本页 10 个操作，其中 10 个在本平台绑定中声明了方法签名。

跨端方法名

操作	Android	Web	Electron	macOS	Flutter	Native (C ABI)	iOS
`createConversationTag`	`createConversationTag`	`createConversationTag`	`createConversationTag`	`createConversationTag`	`createConversationTag`	—	`func`
`updateConversationTag`	`updateConversationTag`	`updateConversationTag`	`updateConversationTag`	`updateConversationTag`	`updateConversationTag`	—	`func`
`deleteConversationTag`	`deleteConversationTag`	`deleteConversationTag`	`deleteConversationTag`	`deleteConversationTag`	`deleteConversationTag`	—	`func`
`getConversationTags`	`getConversationTags`	`getConversationTags`	`getConversationTags`	`getConversationTags`	`getConversationTags`	—	`func`
`addConversationsToTag`	`addConversationsToTag`	`addConversationsToTag`	`addConversationsToTag`	`addConversationsToTag`	`addConversationsToTag`	—	`func`
`removeConversationsFromTag`	`removeConversationsFromTag`	`removeConversationsFromTag`	`removeConversationsFromTag`	`removeConversationsFromTag`	`removeConversationsFromTag`	—	`func`
`getConversationsFromTagByPage`	`getConversationsFromTagByPage`	`getConversationsFromTagByPage`	`getConversationsFromTagByPage`	`getConversationsFromTagByPage`	`getConversationsFromTagByPage`	—	`func`
`getTagsFromConversation`	`getTagsFromConversation`	`getTagsFromConversation`	`getTagsFromConversation`	`getTagsFromConversation`	`getTagsFromConversation`	—	`func`
`getUnreadCountByTag`	`getUnreadCountByTag`	`getUnreadCountByTag`	`getUnreadCountByTag`	`getUnreadCountByTag`	`getUnreadCountByTag`	—	`func`
`setConversationToTopInTag`	`setConversationToTopInTag`	`setConversationToTopInTag`	`setConversationToTopInTag`	`setConversationToTopInTag`	`setConversationToTopInTag`	—	`func`

方法名在 GA 平台之间保持一致（规则 A）；Native C ABI 只覆盖部分操作，其余操作以 — 标注。

createConversationTag

创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。

createConversationTag(params: CreateConversationTagParam): Promise<IAsyncResult<ConversationTag>>

REST（客户端）since 1.2.0

参数

参数	类型	说明
`tagName`	`string`	必填；字段含义见类型定义
`options`	`{tagId?:string}`	可选；选项对象（字段见类型列）：{ tagId?:string }

ConversationTag 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.createConversationTag({ tagName: '工作' });
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	400	否	参数错误
`1031`	`TAG_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	400	否	单用户会话标签数超过上限（20）

updateConversationTag

重命名会话标签。

updateConversationTag(tagId: string, tagName: string): Promise<IAsyncResult<ConversationTag>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义
`tagName`	`string`	必填；字段含义见类型定义

ConversationTag 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.updateConversationTag('tag_1001', '工作');
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	400	否	参数错误
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在

deleteConversationTag

删除会话标签（同时清除标签内会话引用）。

deleteConversationTag(tagId: string): Promise<IAsyncResult<null>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义

void 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.deleteConversationTag('tag_1001');
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在

getConversationTags

获取全部会话标签（含会话数量）。

getConversationTags(): Promise<IAsyncResult<ConversationTag[]>>

REST（客户端）幂等since 1.2.0

ConversationTag[] ConversationTag 列表

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.getConversationTags();
if (res.code !== 0) { console.error(res.msg); }

该操作未声明专属错误码；失败时按 SDK 通用错误处理，见状态码。

addConversationsToTag

把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。

addConversationsToTag(tagId: string, conversations: ConversationRef[]): Promise<IAsyncResult<ConversationTagMembershipResult>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义
`conversations`	`ConversationRef[]`	必填；字段含义见类型定义

{added:int, existing:int, conversationCount:int} 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.addConversationsToTag('tag_1001', [{ conversationType: ConversationType.PRIVATE, targetId: 'user2' }]);
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	400	否	参数错误
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在
`1033`	`TAG_CONVERSATION_LIMIT_EXCEEDED`	客户端 / 参数 / 权限	400	否	标签内会话数超过上限（1000）

removeConversationsFromTag

把会话移出标签（≤100/次，幂等）。

removeConversationsFromTag(tagId: string, conversations: ConversationRef[]): Promise<IAsyncResult<ConversationTagMembershipResult>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义
`conversations`	`ConversationRef[]`	必填；字段含义见类型定义

{removed:int, conversationCount:int} 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.removeConversationsFromTag('tag_1001', [{ conversationType: ConversationType.PRIVATE, targetId: 'user2' }]);
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	400	否	参数错误
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在

getConversationsFromTagByPage

分页获取标签内会话（含置顶/未读数/最后消息时间）。

getConversationsFromTagByPage(tagId: string, options?: ConversationTagPageOptions): Promise<IAsyncResult<ConversationTagPage>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义
`options`	`{offset?:uint32, limit?:uint32}`	可选；选项对象（字段见类型列）：{ offset?:uint32, limit?:uint32 }

{total:int, items:ConversationTagConversation[]} 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.getConversationsFromTagByPage('tag_1001', {  });
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在

getTagsFromConversation

查询某个会话所属的标签列表。

getTagsFromConversation(conversationType: number, targetId: string): Promise<IAsyncResult<ConversationTag[]>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`conversationType`	`ConversationType`	必填；会话类型枚举（ConversationType）
`targetId`	`string`	必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId

ConversationTag[] ConversationTag 列表

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.getTagsFromConversation(ConversationType.PRIVATE, 'user2');
if (res.code !== 0) { console.error(res.msg); }

该操作未声明专属错误码；失败时按 SDK 通用错误处理，见状态码。

getUnreadCountByTag

标签内未读汇总（消息总数 + 有未读的会话数）。

getUnreadCountByTag(tagId: string): Promise<IAsyncResult<ConversationTagUnread>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义

{unreadCount:int, unreadConversations:int, conversationCount:int} 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.getUnreadCountByTag('tag_1001');
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1032`	`TAG_NOT_FOUND`	客户端 / 参数 / 权限	404	否	标签不存在

setConversationToTopInTag

标签内置顶/取消置顶会话（同步会话会话级置顶状态）。

setConversationToTopInTag(tagId: string, conversationType: number, targetId: string, top: boolean): Promise<IAsyncResult<null>>

REST（客户端）幂等since 1.2.0

参数

参数	类型	说明
`tagId`	`string`	必填；字段含义见类型定义
`conversationType`	`ConversationType`	必填；会话类型枚举（ConversationType）
`targetId`	`string`	必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
`top`	`bool`	必填；字段含义见类型定义

void 成功返回的数据；失败时按错误码处理

示例

// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.setConversationToTopInTag('tag_1001', ConversationType.PRIVATE, 'user2', true);
if (res.code !== 0) { console.error(res.msg); }

错误码

错误码	名称	分类	HTTP	可重试	说明
`1001`	`INVALID_PARAMETER`	客户端 / 参数 / 权限	400	否	参数错误
`1034`	`CONVERSATION_NOT_FOUND`	客户端 / 参数 / 权限	404	否	会话不存在（标签内置顶等操作要求会话已在标签内）

会话标签与分组

接口一览​

跨端方法名​

createConversationTag​

updateConversationTag​

deleteConversationTag​

getConversationTags​

addConversationsToTag​

removeConversationsFromTag​

getConversationsFromTagByPage​

getTagsFromConversation​

getUnreadCountByTag​

setConversationToTopInTag​

相关文档​

接口一览

跨端方法名

createConversationTag

updateConversationTag

deleteConversationTag

getConversationTags

addConversationsToTag

removeConversationsFromTag

getConversationsFromTagByPage

getTagsFromConversation

getUnreadCountByTag

setConversationToTopInTag

相关文档