Chatroom Attribute Management (KV)

The SDK provides chatroom attribute (KV) management interfaces in the core chatroom business class RongChatRoomClient (you can also use RongIMClient) to set custom attributes in a specified chatroom.

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

Enabling the Service

Using the chatroom attribute (KV) interface requires enabling the Chatroom Custom Attributes service. You can enable this service by visiting the Basic Features page in the Console.

The chatroom business also provides server-side callback functionality, allowing the RC server to synchronize all chatroom attribute changes (set, delete, delete all, etc.) to a specified address, making it easier for your app's backend to track chatroom attribute changes. For more details, refer to the server-side documentation Chatroom Attribute Synchronization (KV).

Limitations

tip

Once a chatroom is destroyed, all custom attributes within it are also destroyed.
Each chatroom allows a maximum of 100 attributes to be stored in Key-Value pairs.
The client SDK does not limit the frequency of KV operations. However, it is recommended to keep the frequency of Key-Value operations within 100 times per second for each chatroom (a single operation involving 100 KVs is equivalent to 100 operations).

Monitoring Chatroom Attribute Changes

The SDK provides the KVStatusListener in the core chatroom business class RongChatRoomClient to monitor changes in chatroom attributes (KV). You can also use the interface class of the same name under RongIMClient.

Return Value	Method	Description
void	`onChatRoomKVSync(String roomId)`	Triggered when the chatroom KV list synchronization is completed.
void	`onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)`	Triggered when the chatroom KV list is updated. The first synchronization returns all KVs, subsequent triggers return only new or modified KVs.
void	`onChatRoomKVRemove(String roomId, Map<String, String> chatRoomKvMap)`	Triggered when a KV is deleted.

onChatRoomKVSync(String roomId)

Triggered when: After successfully joining a chatroom, the SDK synchronizes the KV list from the server by default, and triggers this callback upon completion.

Parameter Type Description
roomId String Chatroom ID
onChatRoomKVUpdate(String roomId, Map<String, String> chatRoomKvMap)

Triggered when: Chatroom KV is updated.

If KVs exist when you first join the chatroom, this callback will return all KVs. Subsequent callbacks will return incremental data for KVs set or modified by others.

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

Triggered when: A KV is deleted.

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

Parameter	Type	Description
roomId	String	Chatroom ID

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

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

Adding a Chatroom KV Listener

Use the addKVStatusListener method to add a chatroom KV listener KVStatusListener. Multiple listeners can be set. To avoid memory leaks, remove the listener when it is no longer needed.

RongChatRoomClient.getInstance().addKVStatusListener(listener);

Removing a Chatroom KV Listener

The SDK supports removing listeners. To avoid memory leaks, remove the listener when it is no longer needed.

RongChatRoomClient.getInstance().removeKVStatusListener(listener);

Retrieving a Single Attribute

Retrieve a single KV attribute from a specified chatroom using the attribute's Key.

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

           }
 });

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters.
callback	ResultCallback<Map<String, String>>	Callback interface

Retrieving All Attributes

Retrieve all KV pairs from a specified chatroom.

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

            }
        });

Parameter	Type	Description
chatRoomId	String	Chatroom ID
callback	ResultCallback<Map<String, String>>	Callback interface

Setting a Single Attribute

Set a single KV pair in a specified chatroom. Note that this interface does not support updating existing attributes.

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

    }
});

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

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

Force Setting a Single Attribute

Force set a chatroom attribute. Stored as key = value. If the key does not exist, it adds the attribute. If the key already exists, it updates the attribute's value. Using force setting allows modifying attributes created by others.

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

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

    @Override
    public void onSuccess() {

    }


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

    }
});

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

Batch Setting Attributes

Batch set chatroom attributes. The isForce parameter controls whether to forcibly overwrite attributes set by others.

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

    }
});

Parameter	Type	Description
chatRoomId	String	Chatroom ID
chatRoomEntryMap	Map	The maximum size of the `chatRoomEntryMap` collection is 10. Exceeding this limit will return the error code `KV_STORE_OUT_OF_LIMIT` (23429).
isAutoDel	boolean	Whether to automatically delete the Key and Value when the user goes offline or exits the chatroom.
isForce	boolean	Whether to forcibly overwrite
callback	SetChatRoomKVCallback	Callback interface

If some operations fail, 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 is the failed key, value is the corresponding error code).

Deleting a Single Attribute

Delete a single attribute from a specified chatroom. This interface only supports deleting attributes created by the current user.

String chatRoomId = "Chatroom ID";
String key = "name";
boolean sendNotification = true;
String notificationExtra = "Notification message extension";

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

    @Override
    public void onSuccess() {

    }


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

    }
});

When deleting a KV, you can specify the SDK to send a chatroom attribute notification message (ChatRoomKVNotiMessage). For details on the message content structure, refer to Notification Message Format.

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

Force Deleting a Single Attribute

Force delete a single attribute from a specified chatroom. This allows deleting attributes created by others.

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

    }
});

When force deleting a KV, you can specify the SDK to send a chatroom attribute notification message (ChatRoomKVNotiMessage). For details on the message content structure, refer to Notification Message Format.

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters.
sendNotification	boolean	`true` to send a notification; `false` to not send. If a notification is sent, the SDK will receive a `RC:chrmKVNotiMsg` notification message (`ChatRoomKVNotiMessage`), containing the KV.
notificationExtra	String	Custom field for the notification. The `RC:chrmKVNotiMsg` (`ChatRoomKVNotiMessage`) notification message will include this field, with a maximum length of 2048 characters.
callback	OperationCallback	Callback interface

Batch Deleting Attributes

Batch delete attributes from a specified chatroom. A maximum of 10 attributes can be deleted in a single operation. The isForce parameter controls whether to forcibly delete attributes set by others.

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

    }
});

Parameter	Type	Required	Description
chatRoomId	String	Yes	Chatroom ID
keys	List	Yes	Collection of chatroom attribute names, with a maximum size of 10.
isForce	boolean	Yes	Whether to forcibly overwrite
callback	SetChatRoomKVCallback	Yes	Callback interface

If some operations fail, 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 have values (key is the failed key, value is the corresponding error code).

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Chatroom Attribute Management (KV)

Enabling the Service​

Limitations​

Monitoring Chatroom Attribute Changes​

Adding a Chatroom KV Listener​

Removing a Chatroom KV Listener​

Retrieving a Single Attribute​

Retrieving All Attributes​

Setting a Single Attribute​

Force Setting a Single Attribute​

Batch Setting Attributes​

Deleting a Single Attribute​

Force Deleting a Single Attribute​

Batch Deleting Attributes​