聊天室属性（KV）概述

聊天室属性（KV）管理功能允许您在指定聊天室中设置自定义键值对（KV）。该功能适用于以下典型场景：

• 语音直播：记录各麦位状态（空闲/占用）
• 卡牌游戏：存储玩家角色和牌局状态
• 互动课堂：维护答题进度和分数

客户端可通过注册监听器实时获取属性变更通知。

开通服务

使用聊天室属性（KV）功能前，您需要为当前 App Key 开通聊天室自定义属性。开通服务后，客户端与服务端均可以设置聊天室自定义属性（KV）。

服务限制

• 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
• 聊天室销毁后，聊天室中的自定义属性同时销毁。
• 聊天室 KV 也受聊天室消息抛弃策略影响。如要确保设置属性通知消息不被丢弃，您可以使用聊天室白名单服务中的用户白名单进行保护。详见开通聊天室白名单服务。
• 调用客户端与服务端 API 均可以操作聊天室属性 KV，当前即时通讯服务未对总操作频率进行限制。为确保您的 App 业务正常运行，建议将单个聊天室房间操作 Key-Value 的总频率维持在100 对/每秒及以下（一秒内单次操作 100 对 KV）。

属性管理接口

开通服务后，您可以使用以下接口：

• 设置聊天室属性：在指定聊天室中设置一个自定义属性 KV 对。该接口要求同时传入操作用户 ID，作为该 KV 对的所属用户。
• 批量设置聊天室属性：在指定聊天室中批量、强制设置自定义属性 KV 对，单次最多 20 个 KV 对。如果属性已存在，该接口会强制覆盖原有 KV 对的所属用户 ID 和 Value。
• 删除聊天室属性：在指定聊天室中删除一个自定义属性 KV 对。该接口要求同时传入该 KV 对的所属用户 ID。
• 批量删除聊天室属性：在指定聊天室中批量、强制删除自定义属性 KV 对，单次最多 20 个 KV 对。该接口会强制删除 KV 对，不要求传入待删除 KV 对的所属用户 ID。应用中管理员角色用户可使用该接口清除指定聊天室内的业务数据。

监控聊天室自定义属性变化

您可以使用以下方式监控聊天室属性的变化：

• 服务端回调：您可以在控制台自助配置接收聊天室属性的回调 URL。即时通讯服务端会将应用下的全部聊天室属性变化（设置、删除、全部删除等操作）同步到您指定的地址，方便 App 业务服务端了解聊天室属性变化。详见聊天室属性同步（KV）。
• 客户端回调：客户端 SDK 提供了聊天室属性变化的监听器，可监听聊天室属性同步、设置、删除等操作。