Chatroom Attribute Management (KV)

The IMLib SDK provides chatroom attribute (KV) management interfaces in the core chatroom business class [RongChatRoomClient], allowing custom attributes to be set in specified chatrooms.

In voice live streaming chatroom scenarios, this feature can be used to record attributes of different microphone positions; or in card games like Werewolf, it can track user roles and game states.

Service Activation

Using chatroom attribute (KV) interfaces requires enabling the Chatroom Custom Attributes service. You can activate this service in the RC Console at Chat > Chat settings > Chatroom.

The chatroom service provides server-side callback functionality, allowing RC's servers to synchronize all chatroom attribute changes (set, delete, bulk delete operations) within your application to a specified endpoint, enabling your app's backend to track attribute changes. For details, see the server-side documentation Chatroom Attribute Synchronization (KV).

Limitations

tip

• When a chatroom is destroyed, all its custom attributes are also removed.
• Each chatroom supports a maximum of 100 attribute entries stored as Key-Value pairs.
• The client SDK imposes no rate limits on KV operations. We recommend keeping KV operations below 100 actions per second per chatroom (a single operation affecting 100 KVs counts as 100 actions).

Monitoring Chatroom Attribute Changes

The SDK provides [KVStatusListener] in the core chatroom business class [RongChatRoomClient] to monitor chatroom attribute (KV) changes.

Return	Method	Description
void	onChatRoomKVSync(String roomId)	Triggered when chatroom KV synchronization completes.
void	onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)	Triggered when chatroom KV updates complete. Returns all KVs during initial sync, then only new/modified KVs subsequently.
void	onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap)	Triggered when KVs are deleted.

• onChatRoomKVSync(String roomId)

  Trigger: When joining a chatroom succeeds, IMLib SDK automatically syncs KVs from the server, triggering this upon completion.

  Parameter	Type	Description
  roomId	String	Chatroom ID

• onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)

  Trigger: When chatroom KVs are updated.

  If KVs exist when first joining, this callback returns all KVs; subsequent callbacks return only incremental changes made by others.

  Parameter	Type	Description
  roomId	String	Chatroom ID
  chatRoomKvMap	Map<String, String>	Changed chatroom KVs

• onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap)

  Trigger: When KVs are deleted.

  Parameter	Type	Description
  roomId	String	Chatroom ID
  chatRoomKvMap	Map<String, String>	Deleted chatroom KVs

Adding a Chatroom KV Listener

Use [addKVStatusListener] to add a [KVStatusListener]. Multiple listeners are supported. Remove listeners when no longer needed to prevent memory leaks.

Interface Prototype

RongChatRoomClient.getInstance().addKVStatusListener(listener);

Removing a Chatroom KV Listener

The SDK supports listener removal. Remove listeners when no longer needed to prevent memory leaks.

Interface

RongChatRoomClient.getInstance().removeKVStatusListener(listener);

Extended Chatroom KV Listener

For strictly ordered KV change notifications, use KVStatusExListener. This interface extends KVStatusListener with an additional onChatRoomKVChange() method.

Sample Code

RongChatRoomClient.getInstance().addKVStatusListener(new RongChatRoomClient.KVStatusExListener() {
    @Override
    public void onChatRoomKVSync(String roomId) {
    }

    @Override
    public void onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap) {
    }

    @Override
    public void onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap) {
    }

    /**
     * Callback for chatroom KV changes.
     * Includes data from both onChatRoomKVUpdate and onChatRoomKVRemove.
     * 
     * @param roomId Chatroom ID
     * @param changeInfos Changed KVs, strictly ordered by modification sequence.
     */
    @Override
    public void onChatRoomKVChange(String roomId, ChatroomKVChangeInfo[] changeInfos) {
    }
});

Retrieving a Single Attribute

Use [getChatRoomEntry] to fetch a specific KV from a chatroom by its Key.

Interface

RongChatRoomClient.getInstance().getChatRoomEntry(chatRoomId, key, callback);

Parameters

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Attribute name. Supports uppercase/lowercase letters, numbers, and special characters + = - _, max 128 chars
callback	ResultCallback<Map<String, String>>	Callback interface

Sample Code

String chatRoomId = "Chatroom ID";
String key = "name";

RongChatRoomClient.getInstance().getChatRoomEntry(chatRoomId, key, new IRongCoreCallback.ResultCallback<Map<String, String>>() {
        @Override
        public void onSuccess(Map<String, String> stringStringMap) {

            }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {

           }
 });

Retrieving All Attributes

Use the [getAllChatRoomEntries] method to retrieve all key-value pairs of attributes in a specified chatroom.

Interface

RongChatRoomClient.getInstance().getAllChatRoomEntries(chatRoomId, callback);


#### Parameter Description


| Parameter    | Type                                   | Description      |
|:-------------|:---------------------------------------|:----------------|
| chatRoomId   | String                                 | Chatroom ID      |
| callback     | ResultCallback\<Map\<String, String\>> | Callback interface |


#### Example Code

```java
String chatRoomId = "Chatroom ID";

RongChatRoomClient.getInstance().getAllChatRoomEntries(chatRoomId, new IRongCoreCallback.ResultCallback<Map<String, String>>() {
         @Override
         public void onSuccess(Map<String, String> stringStringMap) {

            }

          @Override
         public void onError(IRongCoreEnum.CoreErrorCode e) {

            }
        });


## Setting a Single Attribute

Use the [setChatRoomEntry] method to set a single key-value pair attribute in a specified chatroom. Note that this interface does not support updating existing attributes.


#### Interface

```java
RongChatRoomClient.getInstance().setChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, callback);


#### Parameter Description

When setting KV pairs, you can specify the SDK to send a chatroom attribute notification message (`ChatRoomKVNotiMessage`). For message content structure details, refer to [Notification Message Format].

| Parameter           | Type              | Description                                                                                                                                                        |
|:--------------------|:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chatRoomId          | String            | Chatroom ID                                                                                                                                                       |
| key                 | String            | Chatroom attribute name. Key supports uppercase/lowercase letters, numbers, and special characters + = - _, with a maximum length of 128 characters               |
| value               | String            | Value corresponding to the chatroom attribute, with a maximum length of 4096 characters                                                                            |
| sendNotification    | boolean           | `true` to send notification; `false` to not send. If notification is sent, the SDK will receive a chatroom attribute notification message (`ChatRoomKVNotiMessage`) with type identifier `RC:chrmKVNotiMsg`, containing K and V in the message content |
| autoDelete          | boolean           | Whether to delete after exiting                                                                                                                                   |
| notificationExtra   | String            | Custom field for notifications. The `RC:chrmKVNotiMsg` (`ChatRoomKVNotiMessage`) notification message will include this field, with a maximum length of 2048 characters                                                       |
| callback            | OperationCallback | Callback interface                                                                                                                                                |


#### Example Code

```java
String chatRoomId = "Chatroom ID";
String key = "name";
String value = "RongRong";
boolean sendNotification = true;
boolean isAutoDel = false;
String notificationExtra = "Notification message extension";

RongChatRoomClient.getInstance().setChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});


## Force Setting a Single Attribute

Use the [forceSetChatRoomEntry] method to forcibly set chatroom attributes in key-value pair format. When the key does not exist, it represents adding an attribute. When the key already exists, it represents updating the attribute value. Forced setting allows modifying attribute values created by others. When setting KV pairs, you can specify the SDK to send a chatroom attribute notification message (`ChatRoomKVNotiMessage`). For message content structure details, refer to [Notification Message Format].


#### Interface

```java
RongChatRoomClient.getInstance().forceSetChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, callback);


#### Parameter Description


| Parameter           | Type              | Description                                                                                                                                                        |
|:--------------------|:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chatRoomId          | String            | Chatroom ID                                                                                                                                                       |
| key                 | String            | Chatroom attribute name. Key supports uppercase/lowercase letters, numbers, and special characters + = - _, with a maximum length of 128 characters               |
| value               | String            | Value corresponding to the chatroom attribute, with a maximum length of 4096 characters                                                                            |
| sendNotification    | boolean           | `true` to send notification; `false` to not send. If notification is sent, the SDK will receive a `ChatRoomKVNotiMessage` notification message with type identifier `RC:chrmKVNotiMsg`, containing K and V in the message content |
| autoDelete          | boolean           | Whether to delete after exiting                                                                                                                                   |
| notificationExtra   | String            | Custom field for notifications. The `RC:chrmKVNotiMsg` (`ChatRoomKVNotiMessage`) notification message will include this field, with a maximum length of 2048 characters                                                       |
| callback            | OperationCallback | Callback interface                                                                                                                                                |


#### Example Code


```java
String chatRoomId = "chatroom ID";
String key = "name";
String value = "RongRong";
boolean sendNotification = true;
boolean isAutoDel = false;
String notificationExtra = "Notification extension";

RongChatRoomClient.getInstance().forceSetChatRoomEntry(chatRoomId, key, value, sendNotification, isAutoDel, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }


    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});


## Batch Set Attributes

Use the [setChatRoomEntries] method to batch set chatroom attributes. The `isForce` parameter controls whether to forcibly overwrite attributes set by others.


#### Interface

```java
RongChatRoomClient.getInstance().setChatRoomEntries(chatRoomId, chatRoomEntryMap, isAutoDel, isForce, callback);


#### Parameter Description


| Parameter        | Type                  | Description                                                                                  |
|:-----------------|:----------------------|:--------------------------------------------------------------------------------------------|
| chatRoomId       | String                | Chatroom ID                                                                                 |
| chatRoomEntryMap | Map                   | Maximum size limit for chatRoomEntryMap is 10. Exceeding this limit returns error code KV_STORE_OUT_OF_LIMIT (23429) |
| isAutoDel        | boolean               | Whether to automatically delete the Key-Value pair when the user disconnects or exits        |
| isForce          | boolean               | Whether to forcibly overwrite                                                               |
| callback         | SetChatRoomKVCallback | Callback interface                                                                           |

If partial failures occur, the SDK will trigger the `onError` callback method of [SetChatRoomKVCallback]:

| Callback Parameter | Callback Type      | Description                                                                                                             |
|:-------------------|:-------------------|:-----------------------------------------------------------------------------------------------------------------------|
| errorCode          | CoreErrorCode      | Error code                                                                                                             |
| map                | Map                | When errorCode is KV_STORE_NOT_ALL_SUCCESS (23428), the map will have values (key: failed keys, value: corresponding error codes) |


#### Example Code

```java
RongChatRoomClient.getInstance().setChatRoomEntries(chatRoomId, chatRoomEntryMap, isAutoDel, isForce, new IRongCoreCallback.SetChatRoomKVCallback() {
    /**
     * Success callback
     */
    @Override
    public void onSuccess() {

    }

    /**
     * Failure callback
     * @param errorCode
     * @param map
     */
    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode, Map<String, IRongCoreEnum.CoreErrorCode> map) {

    }
});


## Delete Single Attribute

Use the [removeChatRoomEntry] method to delete a single attribute from a specified chatroom. This interface only supports deleting attributes created by the current user. When deleting KV pairs, you can specify the SDK to send a chatroom attribute notification message (`ChatRoomKVNotiMessage`). For message content structure, refer to [Notification Message Format].


#### Interface

```java
RongChatRoomClient.getInstance().removeChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, callback);


#### Parameter Description

| Parameter         | Type              | Description                                                                                                                          |
|:------------------|:------------------|:------------------------------------------------------------------------------------------------------------------------------------|
| chatRoomId        | String            | Chatroom ID                                                                                                                         |
| key               | String            | Chatroom attribute name. Key supports uppercase/lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters. |
| sendNotification  | boolean           | true: send notification; false: do not send. If sent, the SDK will receive RC:chrmKVNotiMsg notification message ChatRoomKVNotiMessage containing K and V. |
| notificationExtra | String            | Custom field for notifications. This field will be included in the `RC:chrmKVNotiMsg` type notification message `ChatRoomKVNotiMessage`, with a maximum length of 2048 characters. |
| callback          | OperationCallback | Callback interface                                                                                                                  |


#### Example Code

```java
String chatRoomId = "chatroom ID";
String key = "name";
boolean sendNotification = true;
String notificationExtra = "Notification extension";

RongChatRoomClient.getInstance().removeChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }


    @Override
   public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});


## Force Delete Single Attribute

Use the [forceRemoveChatRoomEntry] method to forcibly delete a single attribute from a specified chatroom. This can delete attributes created by others.
When forcibly deleting KV pairs, you can specify the SDK to send a chatroom attribute notification message (`ChatRoomKVNotiMessage`). For message content structure, refer to [Notification Message Format].


#### Interface

```java
RongChatRoomClient.getInstance().forceRemoveChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, callback);


#### Parameter Description

| Parameter         | Type              | Description                                                                                                                          |
|:------------------|:------------------|:------------------------------------------------------------------------------------------------------------------------------------|
| chatRoomId        | String            | Chatroom ID                                                                                                                         |
| key               | String            | Chatroom attribute name. Key supports uppercase/lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters. |
| sendNotification  | boolean           | true: send notification; false: do not send. If sent, the SDK will receive RC:chrmKVNotiMsg notification message ChatRoomKVNotiMessage containing KV. |
| notificationExtra | String            | Custom field for notifications. This field will be included in the `RC:chrmKVNotiMsg` type notification message `ChatRoomKVNotiMessage`, with a maximum length of 2048 characters. |
| callback          | OperationCallback | Callback interface                                                                                                                  |


#### Sample Code

```java
String chatRoomId = "chatroom ID";
String key = "name";
boolean sendNotification = true;
String notificationExtra = "Notification message extension";

RongChatRoomClient.getInstance().forceRemoveChatRoomEntry(chatRoomId, key, sendNotification, notificationExtra, new IRongCoreCallback.OperationCallback() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {

    }
});


## Batch Delete Attributes

Use the [deleteChatRoomEntries] method to batch delete attributes from a specified chatroom. A maximum of 10 attributes can be deleted at once. The `isForce` parameter controls whether to forcibly delete attributes set by others.


#### Interface

```java
RongChatRoomClient.getInstance().deleteChatRoomEntries(chatRoomId, keys, isForce, callback);


#### Parameter Description

| Parameter   | Type                  | Required | Description                                     |
|:------------|:----------------------|:---------|:-----------------------------------------------|
| chatRoomId  | String                | Yes      | Chatroom ID                                    |
| keys        | List                  | Yes      | Collection of chatroom attribute names (max size: 10) |
| isForce     | boolean               | Yes      | Whether to force overwrite                     |
| callback    | SetChatRoomKVCallback | Yes      | Callback interface                             |

If partial failures occur, the SDK will trigger the `onError` callback method of [SetChatRoomKVCallback]:

| Callback Parameter | Callback Type                                   | Description                                                                                                             |
|:-------------------|:-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------|
| errorCode          | CoreErrorCode                                  | Error code                                                                                                             |
| map                | `Map<String, IRongCoreEnum.CoreErrorCode>`     | When errorCode is KV_STORE_NOT_ALL_SUCCESS (23428), the map will contain values (key: failed key, value: corresponding error code) |


#### Sample Code

```java
RongChatRoomClient.getInstance().deleteChatRoomEntries(chatRoomId, keys, isForce, new IRongCoreCallback.SetChatRoomKVCallback() {
    /**
     * Success callback
     */
    @Override
    public void onSuccess() {

    }

    /**
     * Failure callback
     * @param errorCode Error code
     */
    @Override
    public void onError(IRongCoreEnum.CoreErrorCode errorCode, Map<String, IRongCoreEnum.CoreErrorCode> map) {

    }
});
<!-- links -->
[deleteChatRoomEntries]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/delete-chat-room-entries.html
[forceRemoveChatRoomEntry]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/force-remove-chat-room-entry.html
[removeChatRoomEntry]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/remove-chat-room-entry.html
[setChatRoomEntries]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/set-chat-room-entries.html
[forceSetChatRoomEntry]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/force-set-chat-room-entry.html
[setChatRoomEntry]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/set-chat-room-entry.html
[getAllChatRoomEntries]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/get-all-chat-room-entries.html
[addKVStatusListener]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/add-k-v-status-listener.html
[Notification Message Format]: /platform-chat-api/message-about/objectname-notification
[RongChatRoomClient]: https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/index.html
[SetChatRoomKVCallback]: https://doc.rongcloud.cn/apidoc/imlibcore-android/latest/zh_CN/html/-android--i-m-lib-core--s-d-k/io.rong.imlib/-i-rong-core-callback/-set-chat-room-k-v-callback/index.html
[KVStatusListener]: https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/-k-v-status-listener/index.html
[getChatRoomEntry]:https://doc.rongcloud.cn/apidoc/chatroom-android/latest/zh_CN/html/-android--chatroom--s-d-k/io.rong.imlib.chatroom.base/-rong-chat-room-client/get-chat-room-entry.html